[brettheap]

Lane: openreposhape-2 (openRepoShape-2)
Claim: #711 (comment)

v1.1.1. A draft until the v1.1.0 tag. Stacked on #724, which has landed (below). #630, which rewrote the README and handbook around the sentence this changes, has landed too (190133d5), so the docs wording is in this PR now. #792 (#785), which writes into the same paragraph and into quote_arg, landed after that, and main d7befb91 is merged here with it ("Merge round after #792 (#785)", below).

Stacked on

• render-cli-reference.py and tests/: the CLI reference's children write no bytecode under templates/, the launcher guard reads family.py's siblings child, the quoting-sentence inventory follows an aliased quoter, a suffixless tool and each tool's calling functions, and an S5778 pytest.raises builds its argument first (#665) #724 (lane 5, tests: four guards that do not hold what they say: a .pyc the CLI reference's child writes under templates/, a launcher guard blind to family.py, a quoting-sentence inventory with three holes, and an S5778 pytest.raises #665), branch fix/665-four-guards, which rewrote tests/test_readme_windows_quoting_sentence.py's inventory that this extends.
  • Its head 151a0861dd6ce4a82cf78100fd23b86932c166a2 merged with --no-ff as 7fedbb06, on main bf1f099b. No conflicts.
  • It moved to 949fd4dd4197de263900f9ea2feb410d0ef5adf8 ("Merge branch 'main' into fix/665-four-guards", main bf1f099b; the same tree as 7fedbb06), merged as a3e900c7.
  • render-cli-reference.py and tests/: the CLI reference's children write no bytecode under templates/, the launcher guard reads family.py's siblings child, the quoting-sentence inventory follows an aliased quoter, a suffixless tool and each tool's calling functions, and an S5778 pytest.raises builds its argument first (#665) #724 then landed on main as 20004887, blob for blob equal to 949fd4dd in all five files it touched. Main 20004887 is merged as 2f2928dd, with no conflicts; that merge's tree is main's own.
• Main merged three times for the README turn, because it moved while the tests ran. Each merge had no conflicts and a tree equal to git merge-tree's:
  • main 677f9bfa as 0357e7f4. It holds README, AGENTS.md, docs/cli.md and the handbook: pipx install openreposhape is the second way in and the first on native Windows, git-filter-repo is installed in install.sh's order and never with a bare pip install, and a first draft of the v1.1.0 release notes (#563) #630 (190133d5) and tests/: the quoting-sentence inventory sees a quoter handed on as a value and pins each function's host-dialect calls, and the launcher guard reads run_child and run([PYTHON, ...]), with rows for cli.py and setup-project.py (#759) #808 (677f9bfa).
  • main 5fc049b7 as 1a285512. It adds tests/test_doctor_legs_members_next.py and 24 other files: tests append what they tell git to the GIT_CONFIG_COUNT entries the environment holds, so a pasted line keeps the session's maintenance settings and the Windows job's two (#758) #818, shape-doctor.py: a conflicted shape pin's NEXT takes the side whose pin reads, and names no line where no side's pin reads, so run as printed it no longer leaves the doctor naming the same NEXT again (#752) #779, family.py: add, bump and remove refuse a cherry-pick or a revert stopped in a holder whose refs are a reftable, asking its ref store for CHERRY_PICK_HEAD and REVERT_HEAD by their exact names where no file holds them (#684) #846, siblings.py: a file, or a folder make siblings cannot list or enter, at ../<Project> is NOT A CLONE, reported and left as it is, so the run no longer ends in a traceback at iterdir before the members after it are placed, and make park no longer ends in one over a folder it cannot enter (#735) #772, README.md, the handbook, AGENTS.md and the family-root docs: init's --into sentence names the family-landing-in-standard refusal, make siblings is described as it stops before cloning, and members/ has its one-spelling rule (#695) #738 (e62b5e17, README § Families), scripts/shape_materialize.py and adopt-project.py: a --pin-source that is no clone's top level is refused pin-source-not-a-clone, and check finds a recorded one before a partial clone's NOTE, so a folder inside a clone no longer records the digest of part of its tree, or of nothing (#800) #842 and family.py, scaffold-project.py and bump-leg.py: init's plan rows, seven refusals and bump-leg's root name each path as shown_path names it, so an ESC or a line break in a holder, folder, lock, local remote or root no longer reaches the terminal from those plan rows or those refusals' details #814.
  • main b9b70692 as 7564e916. It adds validate.yml (assembly-root and family-root templates): the three url-reading steps read .gitmodules by the rules the doctor and siblings.py read it by, so a section git ignores, a section with no path, a path or url beginning with -, an unmerged file or a file git refuses whole no longer puts a repository in the App token or the lists, and a refused file fails the step with its cause (#786) #790 (7b210593, a README line and tests/readme-cap.d/786.txt) and validate-family.py: the wrong-case move back mends .gitmodules, adds --sparse and moves an entry in the way aside, a row's staged removal and a url-less section are findings, and two refusals name a cure that works (#762) #820.
  • main d7befb91 as 4ed7d2e0, after shape-doctor.py: a path that is not ASCII is printed as that path in every NEXT, keep line and WHY, as itself where the report's encoding writes its bytes and escaped whole where it does not, so a line naming Projets/Équipe or a Latin-1 name runs as printed (#785) #792 (shape-doctor.py: every non-ASCII character in a path it prints becomes ?, so a NEXT or keep line naming such a path (a member café, a holder under Projets/Équipe) cannot be pasted as printed #785) landed. It adds shape-doctor.py: a path that is not ASCII is printed as that path in every NEXT, keep line and WHY, as itself where the report's encoding writes its bytes and escaped whole where it does not, so a line naming Projets/Équipe or a Latin-1 name runs as printed (#785) #792 (5cbec222), validate-repository-naming.py, validate-manifest.py and validate-pins.py: a legs: that is not a list is manifest-legs in every gate, a chain link or pin that is not a name is a finding, and the naming gate never reads stdin under --project (#714) #826, shape-doctor.py: a shape copy renamed on one side of a merge, conflicted under a name no pin has a row for, is named in a conflicted shape pin's why and left_for_a_person as renamed from that copy, for a person to settle, and never taken (#753) #781, adopt-project.py: plan asks whether it can write --out with its flags, before any work, and refuses a folder, a pipe, a missing folder or one nobody can write in as adopt-out-unwritable, and says plan written to once the plan is on disk, so a mistyped --out no longer ends in a traceback after the whole plan is built (#799) #833, setup-project.py and the assembly root's bootstrap.py: every Python child is told the encoding its words are read in, so a cp1252 stdout gets one encoding from setup, and make bootstrap passes a project whose name the code page cannot hold #851, setup-project.py: a project name typed at the prompt is checked as --project is and an empty line says no name was typed, so ../x, a/b, .. and --help are refused by name, not by an --id hint, a help page or a probe write (#729) #756 and adopt-project.py: check prints the rename-first remedy as execute does, and a plan's recorded source: repository: holds its names where the live source names none, so check and execute both refuse plan-not-the-source (#716) #825. Three files conflicted, and each hunk is composed (below).
• Review four commits. After 2f2928dd: 8d074f16, the change, and 7581ffb9, fix round 1. After 7564e916: 5035128e, README and the handbook, and e15c237b, tests/: the quoting-sentence inventory sees a quoter handed on as a value and pins each function's host-dialect calls, and the launcher guard reads run_child and run([PYTHON, ...]), with rows for cli.py and setup-project.py (#759) #808's review NIT 6 (both below). Then the merge 4ed7d2e0, whose resolution is the merge round below.

What changed

shape-doctor.py's lines, setup-project.py's family lines and the host-quoted lines of scripts/family.py chose PowerShell's dialect wherever os.name was nt, and os.name is nt under Git Bash too, because Git Bash runs the Windows Python. So a line printed in Git Bash was quoted for a shell the person was not in. Brett Heap chose option (a) of #532's Git Bash question at 2026-10-16T13:07:34Z: sh quoting under Git Bash, keyed on MSYSTEM.

1. One question, scripts/repo_shape.py's host_shell_dialect(name=None, environ=None). It answers "nt" (PowerShell) on a Windows host whose environment has no MSYSTEM, or an empty one, and "posix" (sh) everywhere else, Git Bash and every MSYS2 shell included. shell_quoted and shell_line ask it when they get no platform; an explicit platform keeps its meaning. The docstring gives the rule, why MSYSTEM, and the limit: a PowerShell started from inside Git Bash inherits MSYSTEM and is answered sh's, and nothing tries to detect it. It answers nothing about the machine: PYTHON stays python under Git Bash.
2. setup-project.py carries a copy (host_shell_dialect, beside its copy of the quoting), because it runs before any checkout of the standard exists. SHELL_BARE is gone, and the decision moved to call time. It was decided at import from os.name, while the escape asked os.name at each call: two reads of one question. shell_word now asks the question once per call and takes both the alphabet (SHELL_BARE_NT or SHELL_BARE_POSIX) and the escape from that one answer, so MSYSTEM reaches it, whenever it is set. Setup's family lines (family_next_command, L2-29) follow it.
3. shape-doctor.py. quote_arg, restore_from_head, validator_command, bump_leg_command, checkout_notes, submodule_update_next and copy_command ask the question (imported from repo_shape, as PYTHON is). Under Git Bash that gives sh's quoting, cp and not Copy-Item, and env PYTHONPATH=... and not $env:PYTHONPATH = ...;. scaffold_command keeps its entry point and interpreter on the machine (os.name): a Windows machine is handed python setup-project.py from PowerShell and from Git Bash alike, and only its quoting follows the question. The interpreter on every line is still python_command(platform), PYTHON with no platform.
4. scripts/family.py is unchanged. Its host-dialect lines (_print_next, _switch_command, _add_command, _print_next_steps with the cd {shell_quoted(work)} line lane 5 added to the issue, _checked_mount_path) call shell_quoted and shell_line with no platform, so they follow the question.

Measured by a probe that loads each tool in process and gives each module an os whose name is the host's, with MSYSTEM set or unset. PowerShell and POSIX hosts print exactly what they printed before. Under Git Bash (nt, MSYSTEM=MINGW64), before and after:

before  doctor copy_command:  Copy-Item -LiteralPath 'C:\Users\Jane O''Neill\open Repo Shape\templates\x.md' -Destination 'C:\Users\Jane O''Neill\work\Atlas\x.md'
after   doctor copy_command:  cp 'C:\Users\Jane O'\''Neill\open Repo Shape\templates\x.md' 'C:\Users\Jane O'\''Neill\work\Atlas\x.md'
before  doctor validator:     $env:PYTHONPATH = 'C:\Users\Jane O''Neill\open Repo Shape\scripts'; python3 'C:\Users\Jane O''Neill\open Repo Shape\templates\assembly-root\scripts\validate-pins.py' --root 'C:\Users\Jane O''Neill\work\Atlas'
after   doctor validator:     env PYTHONPATH='C:\Users\Jane O'\''Neill\open Repo Shape\scripts' python3 'C:\Users\Jane O'\''Neill\open Repo Shape\templates\assembly-root\scripts\validate-pins.py' --root 'C:\Users\Jane O'\''Neill\work\Atlas'
before  doctor scaffold:      python3 'C:\Users\Jane O''Neill\open Repo Shape\setup-project.py' --org <your-org> --project Atlas
after   doctor scaffold:      python3 'C:\Users\Jane O'\''Neill\open Repo Shape\setup-project.py' --org <your-org> --project Atlas
before  doctor restore:       git -C 'C:\Users\Jane O''Neill\work\Atlas' checkout HEAD -- scripts/repo_shape.py
after   doctor restore:       git -C 'C:\Users\Jane O'\''Neill\work\Atlas' checkout HEAD -- scripts/repo_shape.py
before  setup family switch:  git -C 'C:\Users\Jane O''Neill\work\Atlas' switch -c family/add-sample
after   setup family switch:  git -C 'C:\Users\Jane O'\''Neill\work\Atlas' switch -c family/add-sample
before  family NEXT STEPS:    cd 'C:\Users\Jane O''Neill\work\Atlas'
after   family NEXT STEPS:    cd 'C:\Users\Jane O'\''Neill\work\Atlas'

(python3 because the probe ran on Linux, where PYTHON is decided at import; a Windows host prints python. bump_leg_command, submodule_update_next, quote_arg, setup's add line and family.py's switch -c and add lines move the same way.) Git Bash reads the before apostrophe as C:\Users\Jane ONeill, and a bare C:\work\Atlas as C:workAtlas.

README and the handbook are in 5035128e (below). No --help text changes, so docs/cli.md is not regenerated.

README and the handbook (5035128e)

#630 owned README and the handbook until it landed, as 190133d5, so the wording waited in docs-wording.md, measured at #630's head b2a62ec7. It is recomputed here on main b9b70692 (the merge 7564e916). Today's old text is byte-identical to the plan's "Old", at the same lines, and the section's old blob is the same 45a3f886.

README.md, "Windows, natively". The first sentence, "Printed commands are quoted for a POSIX shell, so paste them into Git Bash", is kept word for word. The second names init's cd line among family.py's, and its tail changes.

before, README.md:158-161
typed `yes`, which its preflight cannot take there. Printed commands are quoted
for a POSIX shell, so paste them into Git Bash. Only `shape-doctor.py`'s lines,
`setup-project.py`'s family lines and `family.py`'s `NEXT`, `switch -c`, `add`
and `git rm -r --cached` lines are quoted for PowerShell, on Windows.

after, README.md:158-162
typed `yes`, which its preflight cannot take there. Printed commands are quoted
for a POSIX shell, so paste them into Git Bash. Only `shape-doctor.py`'s lines,
`setup-project.py`'s family lines and `family.py`'s `NEXT`, `switch -c`, `add`,
`cd` and `git rm -r --cached` lines are quoted for the shell they are printed
in, PowerShell or Git Bash, on Windows.

docs/handbook.html, panel-windows. The same words, and one sentence README leaves out: the limit host_shell_dialect's docstring names, plus cmd.exe. The widest new line is 100 columns; the panel already runs to 129.

before, docs/handbook.html:737-741
          Printed commands are quoted for a POSIX shell, so paste them into Git Bash. Only
          <code>shape-doctor.py</code>&rsquo;s lines, <code>setup-project.py</code>&rsquo;s family
          lines and <code>family.py</code>&rsquo;s <code>NEXT</code>, <code>switch -c</code>,
          <code>add</code> and <code>git rm -r --cached</code> lines are quoted for PowerShell, on
          Windows.</p>

after, docs/handbook.html:737-744
          Printed commands are quoted for a POSIX shell, so paste them into Git Bash. Only
          <code>shape-doctor.py</code>&rsquo;s lines, <code>setup-project.py</code>&rsquo;s family
          lines and <code>family.py</code>&rsquo;s <code>NEXT</code>, <code>switch -c</code>,
          <code>add</code>, <code>cd</code> and <code>git rm -r --cached</code> lines are quoted for
          the shell they are printed in, PowerShell or Git Bash, on Windows. A shell started from
          inside Git Bash inherits its <code>MSYSTEM</code>, which is how a tool tells Git Bash
          apart, so a PowerShell started there is handed Git Bash&rsquo;s quoting, and cmd.exe is
          handed PowerShell&rsquo;s.</p>

tests/test_readme_windows_quoting_sentence.py's SENTENCE matches the new README sentence once, and the panel holds it once, so the test does not change.

The seven markers. The § Starting a project in a new organisation markers move together, 45a3f886 → 4c523ffe, the blob the plan computed on b2a62ec7. They are at :475, :615, :1093, :1130, :1193, :1449 and :1748; before the panel's three new lines the last five were at :1090, :1127, :1190, :1446 and :1745. The other sections that read this README section (masthead, partway, ci, legs, doublepin, park) were re-read. None says which shell a printed line is quoted for, so only their markers move.

The cap. README goes 1474 → 1475. On main b9b70692 the cap is 1422 + 2 (460.txt) + 5 (550.txt) + 12 (563.txt) + 22 (564.txt) + 10 (606.txt) + 1 (683.txt) + 1 (786.txt) = 1475. tests/readme-cap.d/711.txt adds +1, the line this adds, so the cap is 1476:

+1
2026-10-18
One line for #711, Git Bash's quoting. README's Windows sentence said
`shape-doctor.py`'s lines, setup's family lines and `family.py`'s NEXT,
switch -c, add and git rm -r --cached lines are quoted for PowerShell on
Windows. Since #711 they, and `init`'s cd line, are quoted for the shell
they are printed in: `sh`'s under Git Bash (`MSYSTEM` set) and PowerShell's
in PowerShell. A reader in Git Bash who followed the old sentence would
paste them into PowerShell. Reworded within the sentence, whose first
half, "paste them into Git Bash", is kept word for word; the one line is
the clause that names both shells and `cd`. README goes from 1474 lines to
1475.

• README stays one line under its cap, as main has it. README.md, the handbook, AGENTS.md and the family-root docs: init's --into sentence names the family-landing-in-standard refusal, make siblings is described as it stops before cloning, and members/ has its one-spelling rule (#695) #738 (e62b5e17) cut a line of § Families to fit its own words. validate.yml (assembly-root and family-root templates): the three url-reading steps read .gitmodules by the rules the doctor and siblings.py read it by, so a section git ignores, a section with no path, a path or url beginning with -, an unmerged file or a file git refuses whole no longer puts a repository in the App token or the lists, and a refused file fails the step with its cause (#786) #790's 786.txt then filed its own line as +1.
• This file follows README_CAP_FORMAT: "one … file per issue or pull request that grows README.md … line 1 +N, N the lines it adds".
• Without the file the cap test would still pass (1475 ≤ 1475). It is filed because the format counts the lines a pull request adds, not the room it needs.
• The plan's reason said the old sentence named cd. It did not, and the file says so.

#785 (lane 3's #792) had not landed when this was written. It landed next, as 5cbec222, and the merge round below composes the two. It writes "Off Windows, a path shape-doctor.py cannot print as itself is written $'…'" into this paragraph, and under #711 that is true in Git Bash too. If this lands first, #785 lands its sentence as "Off Windows and in Git Bash", which is three README lines (docs-wording.md section 4, which also gives the handbook words and the final blob, e0d2b672). Its cap file is then computed on the README it lands on.

#808's review, NIT 6 (e15c237b)

#808 (#759) landed first, as 677f9bfa, so NIT 6 of lane 2's review of it (issuecomment-6236457891) falls to this PR.

• The problem. tests/: the quoting-sentence inventory sees a quoter handed on as a value and pins each function's host-dialect calls, and the launcher guard reads run_child and run([PYTHON, ...]), with rows for cli.py and setup-project.py (#759) #808's host_calls counts a host quoter handed on as a value (host_values: map(shell_quoted, w), key=shell_quoted, a functools.partial). But repo_shape.py and the tools that print paste lines: under Git Bash (MSYSTEM set) the host-quoted lines are quoted for sh, not PowerShell, so a pasted NEXT line works in the shell that printed it (#532, option (a)) #711's calls_to, which line_builders and skips_the_question read, counted host_call's calls only. On the merge, ' '.join(map(shell_quoted, w)) if os.name == 'nt' else '' in def a(w) gave set(), while the same line written shell_quoted(x) for x in w gave {'a'}.
• The fix. calls_to adds the functions host_values names. host_values names them as scopes does (<module>, Class.method, a def for its defaults and decorators).
• On the 25 shipped files nothing changes. None hands a quoter on as a value, and each file's line builders, uses and skips are the same before and after (measured by a script in lane 2's scratch, which loads the file before and after the change).
• The test. test_a_quoter_handed_on_as_a_value_beside_os_name_skips_the_question asserts three things: the call form gives {'a'}; the value form gives {'a'}; and a value use told 'posix' (map(functools.partial(shell_quoted, platform='posix'), w)) gives set().
• The mutant. return called in place of return called | {function for function, _ in host_values(tree, names)} (tests/test_readme_windows_quoting_sentence.py:554). The new test fails at its second assert (:657, set() == {'a'}): 1 failed, 191 passed over the quoting file and the trio. Restored; the file's sha256 is 82804a0a before and after.

Tests

tests/test_git_bash_dialect.py (new) emulates each host on any host: each module under test gets an os whose name is the host's (HostOs, through the function's own __globals__), and MSYSTEM is set, empty or unset in the real environment. The real os.name is never patched, so pathlib never sees it. Each line is read back by shlex.split or powershell_words and must give back its words. Hosts: PowerShell (nt, no MSYSTEM), Git Bash (MINGW64), MSYS2 (UCRT64), nt with an empty MSYSTEM, POSIX, and POSIX with MSYSTEM set.

File	Test	Pins
test_git_bash_dialect.py	test_the_question_answers_each_host[6 hosts]	the answer, asked by its two facts and asked on the emulated host; empty MSYSTEM is PowerShell
test_git_bash_dialect.py	test_setups_copy_of_the_question_gives_the_same_answer	setup's copy answers as repo_shape's over 3 os.names x 8 environments, and the two alphabets are the same patterns
test_git_bash_dialect.py	test_shell_quoted_spells_a_word_for_the_hosts_shell[2 values x 6 hosts]	shell_quoted and shell_line with no platform: the exact spelling per dialect, read back whole
test_git_bash_dialect.py	test_an_explicit_platform_keeps_its_meaning_under_git_bash[2]	shell_quoted and quote_arg with "nt"/"posix" under Git Bash
test_git_bash_dialect.py	test_setup_quotes_by_the_same_rule_on_each_host[6]	setup's shell_word equals shell_quoted on every value of the old agreement test, on every host; posix=True stays sh's
test_git_bash_dialect.py	test_setups_family_lines_paste_whole_in_the_hosts_shell[6]	L2-29: family_next_command's switch -c and add
test_git_bash_dialect.py	test_familys_next_steps_paste_whole_in_the_hosts_shell[6]	family.py init's switch -c, add and cd
test_git_bash_dialect.py	test_the_doctors_lines_paste_whole_in_the_hosts_shell[7 lines x 6 hosts]	quote_arg, restore_from_head, bump_leg_command (with its lane trailer), submodule_update_next, checkout_notes, copy_command (cp vs Copy-Item), scaffold_command (python setup-project.py on a Windows machine in either shell)
test_git_bash_dialect.py	test_the_doctors_validator_line_sets_pythonpath_in_the_hosts_shell[6]	$env: for PowerShell, env PYTHONPATH= for sh and Git Bash
test_readme_windows_quoting_sentence.py	test_every_host_dialect_quoter_and_caller_asks_the_one_question	#724's inventory extended: no shipped function that calls a host-dialect quoter, or is one, reads os.name itself, but those READS_OS_NAME_FOR_THE_MACHINE names (shape-doctor.py's scaffold_command). On the base it names shell_quoted, shell_word and the seven doctor functions above
test_readme_windows_quoting_sentence.py	test_reading_os_name_beside_a_host_quoter_skips_the_question	the guard on a synthetic source: an os.name platform, a quoter body, a method, and the exemption by file

Changed: tests/test_family_printed_quoting.py's host_words and the apostrophe test read the host through the question (they read os.name). tests/test_setup_project_py.py::test_the_changed_paste_lines_are_posix_quoted_on_windows_too patched SHELL_BARE, which is gone; it unsets MSYSTEM instead, which with os.name patched is what makes the host PowerShell's.

Mutants, each one line, applied in a scratch clone, run against the two files above (98 tests) and reverted. All 18 are killed:

Mutant	Line at 8d074f1	Killed by
M1 the question ignores MSYSTEM	scripts/repo_shape.py:3315	27 tests, among them test_the_question_answers_each_host[git-bash], test_shell_quoted_spells_a_word_for_the_hosts_shell[...-git-bash], every doctor line [...-git-bash]
M2 an empty MSYSTEM counts as Git Bash ("MSYSTEM" not in environ)	scripts/repo_shape.py:3315	14, among them test_the_question_answers_each_host[empty-msystem], test_setups_copy_of_the_question_gives_the_same_answer
M3 shell_quoted back on os.name	scripts/repo_shape.py:3351	9: test_shell_quoted_spells_a_word_for_the_hosts_shell[...-git-bash], test_familys_next_steps_paste_whole_in_the_hosts_shell[git-bash], the guard test_every_host_dialect_quoter_and_caller_asks_the_one_question
M4 setup's copy ignores MSYSTEM	setup-project.py:2605	5: test_setups_copy_of_the_question_gives_the_same_answer, test_setups_family_lines_paste_whole_in_the_hosts_shell[git-bash], test_setup_quotes_by_the_same_rule_on_each_host[git-bash]
M5 shell_word back on os.name	setup-project.py:2629	5: test_setups_family_lines_...[git-bash], test_setup_quotes_...[git-bash], the guard
M6 shell_word drops posix=True	setup-project.py:2629	2: test_setup_quotes_by_the_same_rule_on_each_host[powershell], [empty-msystem]
M7 quote_arg back on os.name	shape-doctor.py:822	5: test_the_doctors_lines_...[quote_arg-git-bash], [copy_command-git-bash], the guard
M8 restore_from_head back on os.name	shape-doctor.py:1364	3: [restore_from_head-git-bash], [restore_from_head-msys2-ucrt64], the guard
M9 validator_command back on os.name	shape-doctor.py:1825	3: test_the_doctors_validator_line_sets_pythonpath_in_the_hosts_shell[git-bash], [msys2-ucrt64], the guard
M10 bump_leg_command back on os.name	shape-doctor.py:2444	3: [bump_leg_command-git-bash], [...-msys2-ucrt64], the guard
M11 checkout_notes back on os.name	shape-doctor.py:5477	3: [checkout_notes-git-bash], [...-msys2-ucrt64], the guard
M12 submodule_update_next back on os.name	shape-doctor.py:5599	3: [submodule_update_next-git-bash], [...-msys2-ucrt64], the guard
M13 scaffold_command's quoting back on os.name	shape-doctor.py:9108	2: [scaffold_command-git-bash], [...-msys2-ucrt64] (the guard names scaffold_command as reading os.name for the machine, so it is the line test that holds this one)
M14 copy_command's branch back on os.name	shape-doctor.py:5911	3: [copy_command-git-bash], [...-msys2-ucrt64], the guard
M15 scaffold_command picks its entry point by the shell (if target == "nt")	shape-doctor.py:9109	2: [scaffold_command-git-bash], [...-msys2-ucrt64] (Git Bash would be handed setup.sh)
M16 the guard forgets the quoters' own bodies	tests/test_readme_windows_quoting_sentence.py:326	test_reading_os_name_beside_a_host_quoter_skips_the_question
M17 the guard forgets its exemption table	tests/test_readme_windows_quoting_sentence.py:328	the guard on the tools (it names scaffold_command) and test_reading_os_name_...
M18 the guard names every os.name read <module>	tests/test_readme_windows_quoting_sentence.py:312	test_reading_os_name_beside_a_host_quoter_skips_the_question

The mutants ran in a scratch clone holding the change on bf1f099 (c2d27f48), whose +/- lines are byte-identical to 8d074f1's; the line numbers above are 8d074f1's. Every mutant left the other tests of the two files passing. On Linux no test that existed before can see M1-M15: each reads the real os.name, posix, and none sets MSYSTEM with Windows emulated.

Runs (targeted sets, one pytest process at a time; the gh guard first on PATH, GH_TOKEN unset, an empty GH_CONFIG_DIR):

Set	Files	Before: base 7fedbb0	After: the change on 7fedbb0	Final: 8d074f1 (on main 2000488)
A	test_repo_hygiene, test_cli_reference, test_agents_md_codes, test_family_printed_quoting, test_readme_windows_quoting_sentence, test_install_sh, test_dry_run_parity, test_bump_leg_paste_lines, test_pinned_copy_text, test_branch_left_bump_leg_setup, test_bootstrap_after_bump, test_commit_trailers, test_family_tracking_branch, test_update_shape_next_quoting (+ test_git_bash_dialect after; + test_setup_family_folder, test_family_switch_branch_exists, test_validator_child_encoding in final)	781 passed (275.94s)	870 passed (346.86s)	984 passed (380.33s)
B	test_doctor_gitlink_repairs, test_doctor_legs_members_next, test_doctor_next_is_a_command, test_doctor_recorded_answers, test_doctor_validator_rows, test_doctor_validator_verdicts, test_openreposhape_command, test_openreposhape_package, test_setup_project_py	699 passed (731.13s)	699 passed (846.66s)	738 passed (769.05s; main added tests to these files)
C	test_shape_doctor, test_doctor_unfinished_merge	446 passed, 3 skipped, 1 xfailed (623.62s)	446 passed, 3 skipped, 1 xfailed (676.54s)	446 passed, 3 skipped, 1 xfailed (617.70s)

Nothing was red before the change. "After" ran the working tree whose tree, committed, is 73966df1; "Final" ran 8d074f16 itself (A and B started at f578cc02, the same tree before a message-only amend). The list is the brief's: the common set, the five named files, and every test file that names shell_quoted, shell_line, shell_word, quote_arg, MSYSTEM, git_bash_session or a function this changes. tests/test_openreposhape_command.py's test_a_ref_the_doctor_would_check_out_is_validated clones this checkout's HEAD, and is refused at the ref before any doctor runs. merge-tree of 8d074f16 with main 741679e7 (one later commit, tests/conftest.py and a new test file) is clean.

Fix round 1 (7581ffb9)

From rv711's review of 8d074f16: READY, no MUST. This round takes its three SHOULDs and NITs 1-7. One commit on 8d074f16; no rebase.

• SHOULD 1, pinned copies. tests/test_family_printed_quoting.py strips host_shell_dialect from the older library too (ADDED_BY_711, beside ADDED_BY_486). tests/test_pinned_copy_text.py's skew test now reads every pinned script that imports from repo_shape. That adds siblings.py, both bootstrap.py files and validate-manifest.py to validate-pins.py, validate-repository-naming.py and validate-family.py. It refuses host_shell_dialect as it refuses shown_path. validate-manifest.py is a fourth addition beyond the three named, because it too is pinned and imports repo_shape.

• SHOULD 2, the guard. tests/test_readme_windows_quoting_sentence.py's line_builders finds, per file, every function that takes a platform and hands it to a host-dialect quoter or to another such function. In the doctor that is the nine: restore_from_head, validator_command, bump_leg_command, checkout_notes, kept_branch_line, submodule_update_next, lane_trailer_command, copy_command and scaffold_command. skips_the_question counts calls to them as it counts the four quoters, and names a quoter's body by Class.method.

  • copy_command(s, d, os.name) added to shape-doctor.py as a new row is now flagged.
  • The same snippet alone, where no copy_command is defined, is not, because builders are found per file. The test asserts both.
  • Today's 25 tools raise no false positive.
  • The docstring names what it still does not see: a sys.platform branch; from os import name; a module constant built from os.name; a builder imported from another file; and a branch on os.name in a function that calls no quoter and no builder.
  • A quoter that is a method, NIT 6's fourth gap, is now seen rather than named, because bodies are matched by their qualified name.

• SHOULD 3 and NIT 7, docs. docs-wording.md is recomputed at README, AGENTS.md, docs/cli.md and the handbook: pipx install openreposhape is the second way in and the first on native Windows, git-filter-repo is installed in install.sh's order and never with a bare pip install, and a first draft of the v1.1.0 release notes (#563) #630's head b2a62ec7:

  • the old text, byte-identical at README :158-161 and handbook :737-741;
  • the blob, 45a3f886 → 4c523ffe (it was b4fd89e5 before cd was named);
  • the seven markers at :475, :615, :1090, :1127, :1189, :1434, :1733;
  • README 1475 → 1476 against a cap of 1475, hence 711.txt +1.

  It adds init's cd line to family.py's list, and the handbook says cmd.exe is handed PowerShell's quoting. A section on shape-doctor.py: every non-ASCII character in a path it prints becomes ?, so a NEXT or keep line naming such a path (a member café, a holder under Projets/Équipe) cannot be pasted as printed #785 gives the words for both orders. Whichever lands second rewords shape-doctor.py: every non-ASCII character in a path it prints becomes ?, so a NEXT or keep line naming such a path (a member café, a holder under Projets/Équipe) cannot be pasted as printed #785's "Off Windows" to "Off Windows and in Git Bash", not "Outside PowerShell", because cmd.exe is handed PowerShell's quoting. Both orders end at README 1479 and blob e0d2b672.

• NIT 1. tests/test_git_bash_dialect.py's checkout_notes row passes a kept repository, so kept_branch_line's git --git-dir=… branch NAME <commit> is read back per host.

  • A lane name cannot hold an apostrophe: LANE_NAME_RE at scripts/shape_materialize.py:2256 refuses one, and lane_trailer returns None for Dana's lane. So every real trailer reads 'Lane: …' alike in both dialects, and the asked-for LANES_LANE with an apostrophe would print no trailer at all.
  • Instead, test_the_lane_trailer_is_spelled_by_the_lines_own_quoter hands the trailer's quoter Lane: Dana's lane through a stand-in lane_trailer_argument. The bump_leg_command row keeps the real lane 2.

• NITs 2-5, comments only.

  • setup-project.py's SHELL_BARE_NT comment names tests/test_git_bash_dialect.py.
  • tests/test_shape_doctor.py:9585-9588 says quote_arg(value, None) asks host_shell_dialect.
  • tests/test_git_bash_dialect.py says no CI job runs these lines under a real Git Bash: tests-git-bash runs only the launcher and installer suites.
  • scripts/repo_shape.py's module docstring no longer says siblings.py uses shell_quoted.

Mutants of this round, each one line, applied to the worktree by a copy of rv711's mutate.py (P1, P2, D5, D6 are rv711's), run and reverted with a sha256 check. All 7 are killed:

Mutant	Line	Killed by
P1 siblings.py imports host_shell_dialect	templates/family-root/scripts/siblings.py:188	test_siblings_runs_beside_a_repo_shape_without_the_quoter, test_no_pinned_script_imports_what_an_older_library_lacks[siblings]
P2 validate-pins.py imports it	templates/assembly-root/scripts/validate-pins.py:81	test_no_pinned_script_imports_what_an_older_library_lacks[validate-pins]
D5 kept_branch_line(entry, "nt")	shape-doctor.py:5483	test_the_doctors_lines_paste_whole_in_the_hosts_shell[checkout_notes-git-bash], [-msys2-ucrt64], [-posix], [-posix-with-msystem]
D6 lane_trailer_command("nt")	shape-doctor.py:2449	test_the_lane_trailer_is_spelled_by_the_lines_own_quoter[git-bash], [msys2-ucrt64], [posix], [posix-with-msystem]
B1 no line builder is a quoter	tests/test_readme_windows_quoting_sentence.py:360	test_os_name_handed_to_a_line_builder_skips_the_question
B2 a builder handing its platform to another builder is not one	tests/test_readme_windows_quoting_sentence.py:346	test_os_name_handed_to_a_line_builder_skips_the_question
B3 a quoter's body named without its class	tests/test_readme_windows_quoting_sentence.py:362	test_reading_os_name_beside_a_host_quoter_skips_the_question

Runs of this round, on 7581ffb9: set A (the 18 files of the final A above) 995 passed (300.73s), 984 before plus 11 new: the trailer test's 6 hosts, the builder test, and the skew test's 4 new scripts. Before committing, the changed tests alone: 113 passed. tests/test_shape_doctor.py, setup-project.py and scripts/repo_shape.py changed only in comments and a docstring, so B and C were not re-run; the three parse.

Merge round after #792 (#785) (4ed7d2e0)

Lane 3's #792 (#785) landed as 5cbec222. It writes into the README paragraph, the handbook panel and the quote_arg this PR changes. Main d7befb91 holds it, with #826, #781, #833, #851, #756 and #825, and is merged as 4ed7d2e0 ("Merge origin/main (d7befb9) into fix/711-git-bash-dialect after #792 (#785) landed"). Three files conflicted, and each hunk is composed with no change to either side's behaviour:

File	Hunk	This PR (#711)	Main (#792)	Resolution
shape-doctor.py	the repo_shape import	adds host_shell_dialect	adds POWERSHELL_SINGLE_QUOTES	both names
shape-doctor.py	the head of quote_arg	windows from host_shell_dialect(); text still the base's ascii_text(str(value))	text = str(value), windows from os.name, and a value that is not ASCII goes to quoted_beyond_ascii	#792's text and its branch, with #711's windows
README.md	the Windows sentence	the new sentence	the old sentence, then #785's two lines, "Off Windows, a path …"	#711's sentence, then #785's as "Off Windows and in Git Bash, …", three lines (docs-wording.md section 4)
docs/handbook.html	panel-windows	the new sentence and the MSYSTEM limit	the old sentence and #785's	both, #785's reworded the same way, and "a cmd.exe started anywhere else is handed PowerShell's"
docs/handbook.html	the seven markers of § Starting a project in a new organisation	4c523ffe	3d4a01ff	e0d2b672, the merged section's blob (docs-wording.md computed the same)

The "cmd.exe" wording comes from the review of 5035128e. "And cmd.exe is handed PowerShell's" read as a cmd.exe started inside Git Bash too, and that one inherits MSYSTEM and is answered sh's. README names no cmd.exe, so it does not change there. SENTENCE matches once in README's section and once in the panel, and handbook_marker_problems finds nothing. The markers are at :475, :615, :1095, :1132, :1195, :1451 and :1750.

README.md:157-165, after the merge
Git Bash runs step 3's bash command and its one line, tested in CI but for a
typed `yes`, which its preflight cannot take there. Printed commands are quoted
for a POSIX shell, so paste them into Git Bash. Only `shape-doctor.py`'s lines,
`setup-project.py`'s family lines and `family.py`'s `NEXT`, `switch -c`, `add`,
`cd` and `git rm -r --cached` lines are quoted for the shell they are printed
in, PowerShell or Git Bash, on Windows.
Off Windows and in Git Bash, a path `shape-doctor.py` cannot print as itself is
written `$'…'`: bash, zsh and ksh read that; dash (`/bin/sh` on Debian and
Ubuntu) does not.

docs/handbook.html:737-746, after the merge
          Printed commands are quoted for a POSIX shell, so paste them into Git Bash. Only
          <code>shape-doctor.py</code>&rsquo;s lines, <code>setup-project.py</code>&rsquo;s family
          lines and <code>family.py</code>&rsquo;s <code>NEXT</code>, <code>switch -c</code>,
          <code>add</code>, <code>cd</code> and <code>git rm -r --cached</code> lines are quoted for
          the shell they are printed in, PowerShell or Git Bash, on Windows. A shell started from
          inside Git Bash inherits its <code>MSYSTEM</code>, which is how a tool tells Git Bash
          apart, so a PowerShell started there is handed Git Bash&rsquo;s quoting, and a cmd.exe
          started anywhere else is handed PowerShell&rsquo;s. Off Windows and in Git Bash, a path
          <code>shape-doctor.py</code> cannot print as itself is written <code>$'&hellip;'</code>:
          bash, zsh and ksh read that; dash (<code>/bin/sh</code> on Debian and Ubuntu) does not.</p>

quote_arg, composed. A probe called the real host_shell_dialect with each host's os.name and environment, then the merged quote_arg. The report's encoding was ASCII, where the path cannot be printed as itself, or UTF-8, where it can:

Host	host_shell_dialect()	C:\Users\Zoë\work, ASCII report	the same, UTF-8 report	C:\work\Atlas
PowerShell (nt, no MSYSTEM)	nt	('C:\Users\Zo' + [char]0x00EB + '\work')	'C:\Users\Zoë\work'	C:\work\Atlas
cmd.exe (nt, no MSYSTEM)	nt	('C:\Users\Zo' + [char]0x00EB + '\work')	'C:\Users\Zoë\work'	C:\work\Atlas
Git Bash (nt, MSYSTEM=MINGW64)	posix	$'C:\134Users\134Zo\303\253\134work'	'C:\Users\Zoë\work'	'C:\work\Atlas'
POSIX	posix	$'C:\134Users\134Zo\303\253\134work'	'C:\Users\Zoë\work'	'C:\work\Atlas'

That is what README now says: $'…' off Windows and in Git Bash, and PowerShell's quoting in PowerShell and cmd.exe. A path the report can show is quoted as itself in every dialect, and an ASCII value is quoted exactly as before.

• No other dialect choice came in with main. Its one new os.name read in shape-doctor.py is shape-doctor.py: a .gitmodules section name keeps git's own bytes and is handed back to git as them, so configured_url and kept_gitdir find a member named caf\xe9, its detached commit gets its keep line under any locale, and a non-ASCII name no longer ends --root in a UnicodeEncodeError traceback under LC_ALL=C PYTHONUTF8=0 (#732) #774's git_bytes. It picks the type of git's argv (text on Windows, bytes elsewhere) and calls no quoter, so the one-question guard rightly leaves it alone.
• tests/test_doctor_legs_members_next.py and 24 other files: tests append what they tell git to the GIT_CONFIG_COUNT entries the environment holds, so a pasted line keeps the session's maintenance settings and the Windows job's two (#758) #818's PASTE_ENV and ALLOW_FILE_PROTOCOL are in none of this PR's files.

The cap.

• On main d7befb91, README is 1476 lines and the cap is 1422 + 2 (460.txt) + 5 (550.txt) + 12 (563.txt) + 22 (564.txt) + 10 (606.txt) + 1 (683.txt) + 2 (785.txt) + 1 (786.txt) = 1477.
• On top of main this PR adds two lines: its own clause, and the third line of shape-doctor.py: every non-ASCII character in a path it prints becomes ?, so a NEXT or keep line naming such a path (a member café, a holder under Projets/Équipe) cannot be pasted as printed #785's reworded sentence. So tests/readme-cap.d/711.txt is +2; README is 1478 and the cap 1479.
• The cap test prints: README.md is 1478 lines; the cap is 1422 + 2 (460.txt) + 5 (550.txt) + 12 (563.txt) + 22 (564.txt) + 10 (606.txt) + 1 (683.txt) + 2 (711.txt) + 2 (785.txt) + 1 (786.txt) = 1479

+2
2026-10-18
Two lines for #711, Git Bash's quoting. README's Windows sentence said
`shape-doctor.py`'s lines, setup's family lines and `family.py`'s NEXT,
switch -c, add and git rm -r --cached lines are quoted for PowerShell on
Windows. Since #711 they, and `init`'s cd line, are quoted for the shell
they are printed in: `sh`'s under Git Bash (`MSYSTEM` set) and PowerShell's
in PowerShell. A reader in Git Bash who followed the old sentence would
paste them into PowerShell. Reworded within the sentence, whose first
half, "paste them into Git Bash", is kept word for word; one line is the
clause that names both shells and `cd`. The other is #785's sentence after
it, which said a path `shape-doctor.py` cannot print as itself is written
`$'...'` "Off Windows": under #711 Git Bash is handed `sh`'s quoting, so
that spelling too, and the sentence says "Off Windows and in Git Bash",
three lines where it was two. README goes from 1476 lines to 1478.

Runs of the merge round (the same settings as above). The set is #711's own tests, #792's three (test_doctor_non_ascii_paths.py, test_shape_doctor.py, test_stdout_encoding.py), the 21 README and handbook readers, the quoting test, the trio, and every test file that names quote_arg or host_shell_dialect: 29 files.

Run	Tree	Files	Result
before	origin/main ed052f2a	28 (no test_git_bash_dialect.py on main)	2421 passed, 4 skipped (940 + 1481)
the resolution, before its commit	4ed7d2e0's tree	7: the README and handbook checks, the quoting test, the trio, test_git_bash_dialect.py, test_doctor_non_ascii_paths.py	487 passed
after	4ed7d2e0	29	2522 passed, 4 skipped (1033 + 1489). That is 101 more than main's 28 files: the 93 tests of test_git_bash_dialect.py, and 8 that #711 adds to the quoting test (4) and to the pinned-copy skew test (4)

Main moved from ed052f2a to d7befb91 before the merge. Its four new commits (#833, #851, #756, #825) touch none of the three conflicted files; setup-project.py, which #851 and #756 change, merged clean.

Main moved again while the "after" pass ran, to d6475f96 (#788 0905eef5, which changes shape-doctor.py and siblings.py; #822 6fbf3301; #844 d6475f96). None of the three touches README, the handbook, tests/readme-cap.d/ or the quoting test, and git merge-tree of 4ed7d2e0 with it is clean. It is not merged here.

Runs of the README turn

Targeted sets, one pytest process at a time, with GH_TOKEN unset, an empty GH_CONFIG_DIR and S/frbin first on PATH.

• The brief's set is every tests/test_readme_*.py, every test file git grep -l -e 'README.md' -e 'handbook.html' -- tests/ lists (91 on 0357e7f4, 94 on 7564e916), and the trio.
• The direct set (21 files) is the 16 files that read this repository's own README or handbook (two of the trio among them), test_cli_reference.py, and repo_shape.py and the tools that print paste lines: under Git Bash (MSYSTEM set) the host-quoted lines are quoted for sh, not PowerShell, so a pasted NEXT line works in the shell that printed it (#532, option (a)) #711's test_git_bash_dialect.py, test_family_printed_quoting.py, test_setup_project_py.py and test_pinned_copy_text.py.

Run	Tree	Files	Result
before	0357e7f4 (main 677f9bfa)	the brief's set, 91, three batches	6139 passed, 6 skipped, 1 xfailed (2267 + 1543 + 2329; 44:39, 28:49, 21:20)
before	1a285512 (main 5fc049b7)	the direct set	1910 passed, 4 skipped (19:45)
before	7564e916 (main b9b70692)	the direct set	1910 passed, 4 skipped (18:02)
the docs change	5035128e's tree	test_readme_sections.py, test_readme_windows_quoting_sentence.py and the trio	267 passed
NIT 6	e15c237b's tree	test_readme_windows_quoting_sentence.py and the trio	192 passed (191 + the new test)
NIT 6 mutant	return called at :554	the same	1 failed (the new test), 191 passed
after	e15c237b	the brief's set + #711's three, 97, three batches	6665 passed, 6 skipped (2543 + 1511 + 2611; 29:42, 19:10, 27:55)

Nothing was red before. The cap test on 5035128e prints: README.md is 1475 lines; the cap is 1422 + 2 (460.txt) + 5 (550.txt) + 12 (563.txt) + 22 (564.txt) + 10 (606.txt) + 1 (683.txt) + 1 (711.txt) + 1 (786.txt) = 1476.

#818 removed PASTE_ENV and ALLOW_FILE_PROTOCOL. Neither name is in any of #821's nine files after the merges; the one mention left in tests/ is a docstring in main's tests/test_no_auto_maintenance.py:533.

Main moved to ca47b71d while the "after" pass ran (#774 52ff5962, #830 51414d2e, #841 ca47b71d). None of the three touches README, the handbook, tests/readme-cap.d/ or the quoting test, and git merge-tree of e15c237b with it is clean. It is not merged here.

Not changed

• os.name sites that are not the shell, left as they are (line numbers at 8d074f16): scripts/repo_shape.py:135 and setup-project.py:126 (PYTHON, PYTHON_CMD: Git Bash runs the Windows Python, whose command is python); the doctor's python_command, offline (shape-doctor.py:1405, a Windows environment variable is one name whatever its case) and scaffold_command's entry point; setup-project.py:841 (the install offer's argv, cmd /c or bash -c), :1098 (the core.autocrlf preflight), :1372 (the controlling terminal), :2537 and :2558 (the clone's core.autocrlf); adopt-project.py:1042, :1060, :1094, :1128 (path and argv encoding), :5899, :7693 (drive-letter paths); scripts/shape_materialize.py:1994 (a commit message's argv encoding); src/openreposhape/standard.py:275 (the cache directory), :310 (PATHEXT), :446 (rename retries); scripts/render-cli-reference.py:750 (whether there is a bash to render with).
• POSIX already, unchanged: update-shape.py, adopt-project.py, scripts/bump-leg.py, templates/family-root/scripts/validate-family.py, templates/assembly-root/scripts/validate-pins.py and bootstrap.py quote with shlex; scaffold-project.py passes "posix"; scripts/family.py's rm -rf, git mv --sparse, mv and shlex lines are sh's on every host. None calls a host-dialect quoter with no platform.
• templates/family-root/scripts/siblings.py imports the holder's own repo_shape.py and quotes its mv lines with shlex.join, POSIX on every host. It must not import host_shell_dialect, because a holder may keep an older repo_shape.py. Until fix round 1 nothing held that (rv711's SHOULD 1): test_siblings_runs_beside_a_repo_shape_without_the_quoter ran it beside a copy that still had the new name. It now strips host_shell_dialect too (ADDED_BY_711), and tests/test_pinned_copy_text.py's skew test refuses the name in every pinned script that imports from repo_shape.
• src/openreposhape/ has no quoter; cli.py and standard.py print no host-quoted line.
• Pinned copies. No test pins the bytes or digests of scripts/repo_shape.py or siblings.py: a project's contracts/shape-pin.yaml digests are computed from the live file at scaffold time (scripts/shape_materialize.py's COPIED_FROM_SHAPE), and tests/test_pinned_copy_text.py's skew rule (no pinned script imports what an older library lacks) holds, because no pinned script changes; since fix round 1 it reads all seven pinned scripts that import from repo_shape and refuses host_shell_dialect as it refuses shown_path. The copied scripts/repo_shape.py changes, so it rides in v1.1.1's shape bump; no digest is edited.
• README and the handbook: in this PR now (above). AGENTS.md and docs/cli.md say nothing about which shell a printed line is quoted for, and do not change.
• Tests that equate the host default with os.name, left alone: tests/test_shape_doctor.py:3638, :9285, :9436, :9590 (its comment at :9585-9588 now says quote_arg(value, None) asks host_shell_dialect), :9613-9622, :11037, :11125 (line numbers at 7581ffb9), and tests/test_doctor_unfinished_merge.py:54. They hold wherever MSYSTEM is unset, which is every CI job that runs them (Linux), and pass here. A whole-suite run from inside Git Bash would fail them, and the validator and scaffold ones cannot be fixed by swapping the question in, because Git Bash is a third pair (Windows machine, sh shell) that no explicit platform names. A checklist candidate, not this change: tests/test_shape_doctor.py is a hot file.

Closes #711

🤖 Generated with Claude Code

Summary by Sourcery

Make generated Windows commands use the quoting rules of the shell that prints them, including POSIX quoting under Git Bash and MSYS2.

New Features:

• Detect Git Bash and MSYS2 environments through MSYSTEM so generated commands use POSIX quoting in those shells while retaining Windows machine behavior.
• Apply host-shell-aware quoting consistently to repository shape, setup, family, and doctor command output.

Bug Fixes:

• Ensure commands printed under Git Bash paste and execute as complete commands instead of being interpreted with PowerShell quoting.

Enhancements:

• Add coverage for shell dialect selection, command round-tripping across supported hosts, pinned-script compatibility, and static checks that host quoting uses the centralized dialect decision.

Documentation:

• Update the README and handbook to describe shell-specific quoting for PowerShell and Git Bash, including the handling of nested shells and non-ASCII paths.

Tests:

• Add comprehensive emulated-host tests for Git Bash, MSYS2, PowerShell, and POSIX command quoting.

[sourcery-ai]

Reviewer's Guide

This PR makes generated host-specific commands pasteable in Git Bash and other MSYS2 shells by centralizing shell-dialect detection around non-empty MSYSTEM, propagating that decision through setup, doctor, and family output while retaining Windows machine-specific interpreter and entry-point behavior, with extensive emulated-host regression tests.

Sequence diagram for host shell dialect command generation

sequenceDiagram
    participant Caller
    participant Tool as setup/doctor/family
    participant Dialect as host_shell_dialect
    participant Quoter as shell_quoted_or_shell_word

    Caller->>Tool: Generate a command
    Tool->>Dialect: host_shell_dialect()
    Dialect-->>Tool: nt or posix
    Tool->>Quoter: Quote command words using dialect
    Quoter-->>Tool: PowerShell or sh spelling
    Tool-->>Caller: Pasteable command line

    alt Windows with non-empty MSYSTEM
        Dialect-->>Tool: posix
        Tool-->>Caller: sh quoting, cp, env PYTHONPATH
    else Windows without MSYSTEM
        Dialect-->>Tool: nt
        Tool-->>Caller: PowerShell quoting, Copy-Item, $env:PYTHONPATH
    end

Loading

File-Level Changes

Change	Details	Files
Select the shell dialect from the Windows host plus non-empty MSYSTEM, separating machine detection from the shell used to read printed commands.	Add host_shell_dialect() to distinguish PowerShell from Git Bash/MSYS2 while preserving explicit platform overrides. Make host-default quoting use the new runtime decision instead of os.name alone. Keep machine-specific Python and scaffold entry-point selection independent from shell quoting.	scripts/repo_shape.py setup-project.py shape-doctor.py
Propagate Git Bash-aware quoting through all affected generated commands.	Update setup family commands and family next-step switch, add, and cd lines. Update doctor commands, including cp versus Copy-Item and POSIX versus PowerShell PYTHONPATH syntax. Leave explicitly POSIX-quoted commands and unrelated os.name decisions unchanged.	setup-project.py shape-doctor.py scripts/family.py
Add cross-host behavioral and source-level regression coverage for the single dialect decision.	Emulate PowerShell, Git Bash, MSYS2, empty-MSYSTEM, and POSIX environments and round-trip generated lines through the corresponding shell parser. Verify setup's copied dialect logic stays identical to repo_shape.py and explicit platform arguments retain their meaning. Guard against host-quoting callers bypassing host_shell_dialect() while allowing machine-specific exceptions.	tests/test_git_bash_dialect.py tests/test_family_printed_quoting.py tests/test_readme_windows_quoting_sentence.py tests/test_setup_project_py.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#711	Use one host-shell dialect decision so Windows tools run under Git Bash/MSYS2 print POSIX-compatible paste lines, while other Windows hosts retain PowerShell quoting; include the doctor, setup family lines, and family.py lines.	✅
#711	Update the README and handbook to explain that Git Bash receives sh quoting and PowerShell receives PowerShell quoting.	❌	The PR explicitly defers both documentation changes until after #630, and the supplied diff contains no README or handbook edits.

Possibly linked issues

• Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459: The PR implements the issue’s core dialect change across repo_shape.py, setup, the doctor, and family commands; documentation is deferred.

---

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-2, 2026-10-17T12:58:21Z) Independent review of #821 (#711) at 8d074f16: READY

Reviewed 2f2928dd..8d074f16 against #711, in my own clone. There are no MUST findings. Take the three SHOULDs before the PR leaves draft.

SHOULD 1. Nothing stops a pinned script from importing host_shell_dialect.

• tests/test_family_printed_quoting.py:459 (ADDED_BY_486) strips only family.py and siblings.py print commands with unquoted paths, so under a folder with a space the member-git-dir-cached remedy's rm -rf would delete the wrong directory, and add's push line fails #486's five names. So test_siblings_runs_beside_a_repo_shape_without_the_quoter (:463) runs siblings.py beside a copy that still has host_shell_dialect, which no real pre-repo_shape.py and the tools that print paste lines: under Git Bash (MSYSTEM set) the host-quoted lines are quoted for sh, not PowerShell, so a pasted NEXT line works in the shell that printed it (#532, option (a)) #711 holder copy has.
• tests/test_pinned_copy_text.py:777-790 checks only shown_path, and only in validate-pins.py, validate-repository-naming.py and validate-family.py.
• Mutants: adding host_shell_dialect to the import in templates/family-root/scripts/siblings.py:188 or templates/assembly-root/scripts/validate-pins.py:81 survives both tests (4 passed each).
• The PR body's "Not changed" bullet cites that siblings test as the guard.
• Fix: delete host_shell_dialect from the stripped copy too, e.g. an ADDED_BY_711 = ("host_shell_dialect",) deleted beside ADDED_BY_486. Assert in the skew test that it is not imported, and add siblings.py and both bootstrap.py files to that test's scripts. Otherwise, drop the claim from the body.

SHOULD 2. The new guard misses os.name handed to one of the doctor's line builders.

• skips_the_question (tests/test_readme_windows_quoting_sentence.py:318-328) counts only functions that call one of the four HOST_QUOTERS.
• The doctor builds its lines through nine functions that take a platform and pass it to quote_arg: restore_from_head, validator_command, bump_leg_command, checkout_notes, kept_branch_line, submodule_update_next, lane_trailer_command, copy_command and scaffold_command.
• So a new row doing copy_command(src, dst, os.name) hands Git Bash Copy-Item and still passes the guard. Run on "import os\ndef a(s, d):\n return copy_command(s, d, os.name)\n", skips_the_question returns set().
• The docstring at :334-335 says a caller that "passed it as the platform" is caught.
• Fix: per file, treat each function that has a platform parameter and calls a host quoter as a quoter, and count calls to it the way host_calls counts the four. Otherwise, narrow the docstring to the four quoters.

SHOULD 3. Recompute docs-wording.md against the README it is committed on. Lane 3's #785 writes into the same paragraph.

• l3-785-non-ascii-paths (4338345c) adds two README lines directly after this sentence, inside § Starting a project in a new organisation: "Off Windows, a path shape-doctor.py cannot print as itself is written $'…'".
• Under repo_shape.py and the tools that print paste lines: under Git Bash (MSYSTEM set) the host-quoted lines are quoted for sh, not PowerShell, so a pasted NEXT line works in the shell that printed it (#532, option (a)) #711 that also happens on Windows in Git Bash, because quote_arg's windows is False there. Whichever of shape-doctor.py: every non-ASCII character in a path it prints becomes ?, so a NEXT or keep line naming such a path (a member café, a holder under Projets/Équipe) cannot be pasted as printed #785 and repo_shape.py and the tools that print paste lines: under Git Bash (MSYSTEM set) the host-quoted lines are quoted for sh, not PowerShell, so a pasted NEXT line works in the shell that printed it (#532, option (a)) #711 lands second rewords that clause too, for example "Outside PowerShell".
• In either order, recompute on the README the commit lands on: the old text and its lines, the section blob, all seven markers, and README's length against the cap.
• At README, AGENTS.md, docs/cli.md and the handbook: pipx install openreposhape is the second way in and the first on native Windows, git-filter-repo is installed in install.sh's order and never with a bare pip install, and a first draft of the v1.1.0 release notes (#563) #630's current head b2a62ec7 (it has moved on from d2d3d762):
  • The old text is byte-identical at README :158-161 and handbook :737-741.
  • The section blob is still 45a3f886, and the drafted wording turns it into b4fd89e5.
  • The seventh marker is at :1733, not :1732.
  • README is 1475 lines and the cap is 1422 + 53 = 1475, so 711.txt at +1 takes both to 1476.

NIT 1. Two lines are not checked per host; their mutants survive.

• kept_branch_line: tests/test_git_bash_dialect.py:240 passes no kept, so the git --git-dir=… branch NAME <commit> line is never read back per host. The mutant kept_branch_line(entry, "nt") at shape-doctor.py:5483 survives this file and tests/test_doctor_legs_members_next.py (127 passed). Fix: pass kept=[(root / ".git" / "modules" / "spec", COMMIT, None)] and add its words to the row.
• The lane trailer: :288 sets LANES_LANE to lane 2, which both dialects spell 'Lane: lane 2'. So lane_trailer_command("nt") at shape-doctor.py:2449 survives, including against tests/test_shape_doctor.py -k "trailer or bump_leg" plus tests/test_bump_leg_paste_lines.py (36 passed). A lane name with an apostrophe would catch it.
• quote_arg(relative, "nt") in restore_from_head (:1365) also survives, but every caller passes a shape file path that is bare in both dialects, so it changes nothing in practice.

NIT 2. setup-project.py:2586-2589 says tests/test_family_printed_quoting.py holds setup's SHELL_BARE_NT to repo_shape's, but on Linux that file never reaches it. Dropping % from setup's SHELL_BARE_NT survives that file (84 passed) and is killed by tests/test_git_bash_dialect.py (3 failed). Fix: name tests/test_git_bash_dialect.py in the comment.

NIT 3. tests/test_shape_doctor.py:9585-9587 says "quote_arg(value, None) resolves os.name exactly as quote_arg(value, os.name) does". After this PR that is false: it asks host_shell_dialect. The assertion still holds on Linux. Fix: reword the comment, or carry it with the checklist candidate the PR body already names for the other tests that read os.name as the dialect.

NIT 4. tests/test_git_bash_dialect.py:25-26 says "CI's tests-git-bash job is where a real Git Bash runs", which reads as if that job covers these lines. It does not. That job (.github/workflows/tests.yml:233) runs only the launcher and installer suites, from PowerShell, and none of them asserts a host-quoted line. Fix: say that no CI job runs these lines under a real Git Bash.

NIT 5. scripts/repo_shape.py:37-38 is the sentence this PR extends. It still says a holder's scripts/siblings.py spells paths with shell_quoted/shell_line, but siblings.py:1016-1022 uses shlex.join on purpose. This was already wrong before the PR. Fix: drop "and a holder's scripts/siblings.py" while the sentence is being edited.

NIT 6. The guard misses four more patterns; on synthetic sources each returns set():

• a branch on sys.platform;
• from os import name;
• a module-level constant built from os.name;
• a quoter that is a method (os_name_readers calls it Q.quote_arg, the body set calls it quote_arg).

The behaviour rows cover every site that exists today. Fix: name these in the docstring's stated limit.

NIT 7. Two wording points in the docs draft:

• The README list of family.py's lines still leaves out init's cd line. Lane 5's comment on repo_shape.py and the tools that print paste lines: under Git Bash (MSYSTEM set) the host-quoted lines are quoted for sh, not PowerShell, so a pasted NEXT line works in the shell that printed it (#532, option (a)) #711 asked for it to be named, and the PR title names it. "add, cd and git rm -r --cached" fits the same five lines at 80 columns, so it still costs only +1.
• "the shell they are printed in" also covers cmd.exe, which actually gets PowerShell's quoting. Optional.

Checked and true

• The rule.

  • scripts/repo_shape.py:3313-3315 and setup-project.py:2603-2605 are the same logic. A Windows host with MSYSTEM empty or unset is nt; any non-empty MSYSTEM is posix, including " " and lower-case values. Every other host is posix.
  • The test compares the two copies over 3 os.names × 8 environments.
  • My one-copy mutants are all killed: blank counted as unset, empty counted as set, an explicit name or environ ignored, and any non-posix os.name treated as Windows.

• Callers and SHELL_BARE.

  • No shipped caller passes os.name as a platform; the grep finds it only in tests/test_shape_doctor.py:9619-9621 and the guard's synthetic source.
  • SHELL_BARE is used nowhere: not in tests, the docs generator or src/openreposhape. It survives only as a docstring mention at setup-project.py:2618.
  • Every shipped os.name read outside the two copies concerns the machine, not the shell. scaffold_command's is exempt by name.
  • family.py passes no platform or "posix". scaffold-project.py passes "posix". update-shape.py, adopt-project.py, bump-leg.py and shape_materialize.py call no host quoter.

• Doctor lines under Git Bash (reasoned, not run):

  • cp and env are Git for Windows' usr/bin tools.
  • A single-quoted Windows path reaches cp, env, git and python as one word with its backslashes intact.
  • git -C … switch -c and git … submodule update run native git.
  • The old Copy-Item and $env:PYTHONPATH = …; have no meaning in Git Bash.
  • The <Project> and <your-org> placeholders read as redirections if pasted unedited, but that was already true on every POSIX host.

• The scaffold_command split is right. python setup-project.py is README's Windows way in. Git Bash runs the Windows Python and has no python3, and setup.sh would meet the same preflight limit there. Only the quoting follows the shell. The mutant where the interpreter follows the shell is killed.

• Pinned copies.

  • No template script imports host_shell_dialect or any host quoter, so nothing a holder or a project carries needs the new function.
  • family.py and the doctor import the standard checkout's own repo_shape.py.
  • No test pins repo_shape.py's bytes; the change rides v1.1.1's shape bump.

• Tests.

  • The __globals__ stand-in goes through monkeypatch.setitem, and MSYSTEM through setenv/delenv, so both are restored. test_family_printed_quoting.py and the setup test ran after test_git_bash_dialect.py in the same process and passed.
  • The guard raises no false positives on today's tools.
  • The new tests have no composite asserts.
  • The setup family-lines test shares about 3 lines with its older twin, and they differ at words against host_words, so it is below Sonar's duplication block.
  • 18 of my 23 mutants are killed. The 5 survivors are listed above.

• Docs draft (checked at both README, AGENTS.md, docs/cli.md and the handbook: pipx install openreposhape is the second way in and the first on native Windows, git-filter-repo is installed in install.sh's order and never with a bare pip install, and a first draft of the v1.1.0 release notes (#563) #630 heads):

  • The README sentence matches SENTENCE once, and the handbook panel holds it once.
  • 45a3f886 → b4fd89e5 reproduces.
  • The 711.txt text follows README_CAP_FORMAT.

• Merges. merge-tree of 8d074f16 is clean with:

  • main cbff780c;
  • fix/759-quoting-launcher-guards 052410b6;
  • l3-563-docs b2a62ec7;
  • l3-707, 732, 733, 735, 750, 752, 753, 754, 776, 783, 784, 787 and 793.

  Probe merges with main, 759, 630, 732, 733, 754 and 787 pass the three dialect and inventory files.

• The one real conflict is l3-785-non-ascii-paths 4338345c, in shape-doctor.py. It is clean against main alone.

  • Hunk 1 is the repo_shape import list: take both POWERSHELL_SINGLE_QUOTES and host_shell_dialect.
  • Hunk 2 is quote_arg's head: take shape-doctor.py: every non-ASCII character in a path it prints becomes ?, so a NEXT or keep line naming such a path (a member café, a holder under Projets/Équipe) cannot be pasted as printed #785's body with host_shell_dialect() in place of os.name.
  • That resolution passes. Keeping shape-doctor.py: every non-ASCII character in a path it prints becomes ?, so a NEXT or keep line naming such a path (a member café, a holder under Projets/Équipe) cannot be pasted as printed #785's os.name fails 5 tests: the guard plus the quote_arg and copy_command rows for Git Bash and MSYS2.

• l3-544-test-hygiene and l3-548-manifest-kinds already conflict with main alone, so they are stale and not repo_shape.py, setup-project.py, shape-doctor.py, README and the handbook: under Git Bash (MSYSTEM set) the lines that follow the host are quoted for sh, through one question, host_shell_dialect, so the doctor's lines, setup's family lines and family.py's NEXT, switch -c, add and cd lines paste whole in the shell that printed them, and README's Windows sentence says so #821's concern.

• Runs, in lane 2's own clone:

  • the three dialect and inventory files, the setup test and the pinned-copy skew test: 188 passed;
  • 23 one-line mutants: 18 killed and 5 survived, as listed.

Could not verify

• Real Git Bash behaviour. I could not run Git Bash here; these points are reasoned from MSYS2's documented rules:

  • MSYS2 path conversion leaves single-quoted C:\… values unchanged, with or without an apostrophe, both as arguments and in the environment, for env PYTHONPATH=… python, cp and git -C.
  • Git for Windows' launchers export MSYSTEM to children.
  • python resolves to the Windows install rather than the Store stub, and runs these lines without winpty.

  No CI job runs these lines in a real Git Bash.

• The full suite; the writer's A/B/C counts are theirs.

• Which l3-* branches are open PRs. I had no gh, so I classified them by content against main.

• SonarCloud's own analysis of the head.

Lane 2 is taking the three SHOULDs and the NITs in fix round 1 now.

Lane: openreposhape-2 (openRepoShape-2)

[brettheap]

(lane openRepoShape-2, 2026-10-17T13:23:43Z) Re-verification of #821 at 7581ffb9: READY

Fix round 1 is one commit on 8d074f16. It changes tests, comments and docstrings only; shape-doctor.py is unchanged. It was checked read-only in lane 2's own clone, by re-running the saved mutants and probes.

SHOULD 1 (nothing stopped a pinned script importing host_shell_dialect): FIXED

• ADDED_BY_711 is now stripped beside ADDED_BY_486 (tests/test_family_printed_quoting.py:461-465).
• The skew test (tests/test_pinned_copy_text.py:776-811) refuses shown_path and host_shell_dialect in PINNED_IMPORTERS. That list holds all seven pinned scripts that import repo_shape; git grep finds no others.
• P1 (siblings.py imports it) is now killed by the siblings test and by [siblings]. P2 (validate-pins.py imports it) is killed by [validate-pins].

SHOULD 2 (the guard missed os.name handed to a line builder): FIXED

• line_builders finds exactly the doctor's nine builders, plus shell_line in scripts/repo_shape.py, and flags nothing on the 25 tools.
• The review's snippet appended to shape-doctor.py's source is flagged as a_row. In a file that does not define copy_command it is not flagged, which the docstring now states.
• It terminates on recursive builders. It handles a self-recursive builder, two mutually recursive ones, and a cycle that never reaches a quoter (no builders found), and takes 0.52s on a 150-deep chain. Each pass adds a name from a finite set or stops.
• A method builder called through self is caught (P.row).
• Mutants of the new guard die: dropping all builders (L1) and dropping transitivity (L2) are each killed by test_os_name_handed_to_a_line_builder_skips_the_question.

SHOULD 3 (docs plan): FIXED. Every number in docs-wording.md was reproduced on b2a62ec7's own files with its own readme_segments and readme_fingerprint:

• repo_shape.py and the tools that print paste lines: under Git Bash (MSYSTEM set) the host-quoted lines are quoted for sh, not PowerShell, so a pasted NEXT line works in the shell that printed it (#532, option (a)) #711 alone: README 1475 → 1476, section blob 45a3f886 → 4c523ffe.
• README, AGENTS.md, docs/cli.md and the handbook: pipx install openreposhape is the second way in and the first on native Windows, git-filter-repo is installed in install.sh's order and never with a bare pip install, and a first draft of the v1.1.0 release notes (#563) #630 + shape-doctor.py: every non-ASCII character in a path it prints becomes ?, so a NEXT or keep line naming such a path (a member café, a holder under Projets/Équipe) cannot be pasted as printed #785: 1477, blob 3d4a01ff.
• Both orders of repo_shape.py and the tools that print paste lines: under Git Bash (MSYSTEM set) the host-quoted lines are quoted for sh, not PowerShell, so a pasted NEXT line works in the shell that printed it (#532, option (a)) #711 and shape-doctor.py: every non-ASCII character in a path it prints becomes ?, so a NEXT or keep line naming such a path (a member café, a holder under Projets/Équipe) cannot be pasted as printed #785 give the same README: 1479 lines, blob e0d2b672.
• The cap arithmetic holds: +1, or +2 after shape-doctor.py: every non-ASCII character in a path it prints becomes ?, so a NEXT or keep line naming such a path (a member café, a holder under Projets/Équipe) cannot be pasted as printed #785, or shape-doctor.py: every non-ASCII character in a path it prints becomes ?, so a NEXT or keep line naming such a path (a member café, a holder under Projets/Équipe) cannot be pasted as printed #785 at +3 after repo_shape.py and the tools that print paste lines: under Git Bash (MSYSTEM set) the host-quoted lines are quoted for sh, not PowerShell, so a pasted NEXT line works in the shell that printed it (#532, option (a)) #711.
• In every case SENTENCE matches once and the handbook panel holds it once.
• The markers are at :475, :615, :1090, :1127, :1189, :1434 and :1733, and shift by 3 below :741 once the handbook edit lands.
• shape-doctor.py: every non-ASCII character in a path it prints becomes ?, so a NEXT or keep line naming such a path (a member café, a holder under Projets/Équipe) cannot be pasted as printed #785's README and handbook hunks are identical at 4338345c and 26d61255.
• "Off Windows and in Git Bash" is more accurate than the review's "Outside PowerShell": cmd.exe gets PowerShell's quoting.

NIT 1 (two lines not checked per host): FIXED

• D5 (kept_branch_line(entry, "nt")) is killed by the checkout_notes row on four hosts.
• D6 (the trailer always PowerShell's) is killed by test_the_lane_trailer_is_spelled_by_the_lines_own_quoter. Two new trailer mutants also die: D6b (quote_arg(value, "nt")) and D6c (quote_arg(value, "posix")) inside lane_trailer_command.
• The stand-in mirrors the real contract. lane_trailer_argument ends spelled = quote(line) → " --trailer " + spelled, and the stand-in replaces only the lane read and the LANE_NAME_RE gate ([A-Za-z0-9 ()._:/@+-]+, no apostrophe). So the test checks the quoter the doctor hands in, not the stand-in.
• D7 still survives. As noted in round 0, it is equivalent in practice.

NITs 2-7: FIXED.

• 2: setup-project.py:2589-2590 names tests/test_git_bash_dialect.py, and N1 is killed there.
• 3: tests/test_shape_doctor.py:9585-9588 is accurate.
• 4: tests/test_git_bash_dialect.py says no CI job runs these lines under a real Git Bash.
• 5: scripts/repo_shape.py:37-39 no longer names siblings.py.
• 6: the guard's docstring lists the remaining gaps (sys.platform, other spellings of os.name, a module constant, a builder from another file), and a method quoter is now caught (Q.quote_arg).
• 7: cd is named, and the handbook covers cmd.exe.

New, optional NIT. PINNED_IMPORTERS (tests/test_pinned_copy_text.py:776) is a hand list. A future pinned script that imports repo_shape would not be checked until someone adds it. Deriving the list from templates/*/scripts/*.py plus scripts/validate-repository-naming.py would keep it complete.

Merges.

• merge-tree of 7581ffb9 is clean with main 24a977c0, with fix/759-quoting-launcher-guards 052410b6 and with l3-563-docs b2a62ec7.
• l3-785-non-ascii-paths 26d61255 conflicts in the same two shape-doctor.py hunks as before. Take the union of the imports, and shape-doctor.py: every non-ASCII character in a path it prints becomes ?, so a NEXT or keep line naming such a path (a member café, a holder under Projets/Équipe) cannot be pasted as printed #785's quote_arg body with host_shell_dialect() in place of os.name.
• Probe merges pass the dialect, inventory, family-quoting and skew tests: main 196, tests: the quoting-sentence inventory misses a quoter passed as a value and pins functions where it means calls, and the launcher guard has no row for src/openreposhape/cli.py or setup-project.py #759 215, README, AGENTS.md, docs/cli.md and the handbook: pipx install openreposhape is the second way in and the first on native Windows, git-filter-repo is installed in install.sh's order and never with a bare pip install, and a first draft of the v1.1.0 release notes (#563) #630 196, and shape-doctor.py: every non-ASCII character in a path it prints becomes ?, so a NEXT or keep line naming such a path (a member café, a holder under Projets/Équipe) cannot be pasted as printed #785 resolved that way 196.

Runs:

• At 7581ffb9, the dialect, inventory, family-quoting, setup paste-line, skew and scaffold-quoting tests: 200 passed.
• 10 mutants: 9 killed; D7 survives, and is equivalent in practice.

Could not verify. As in round 0:

• real Git Bash behaviour;
• the full suite (the writer's Set A count of 995 is theirs);
• which lane 3 branches are open PRs;
• SonarCloud's analysis of the head.

Lane: openreposhape-2 (openRepoShape-2)

[brettheap]

(lane openRepoShape-2, 2026-10-18T05:26:15Z) Review of #821 (#711)'s new commits (5035128e, e15c237b and the merge round 4ed7d2e0): READY

This verdict is for head 4ed7d2e0, which is now fix/711-git-bash-dialect on origin. No MUST, no SHOULD. Lane 2 lands #821 as reviewed. The four NITs are left on record here; NIT 1 and NIT 2 are test gaps for a later change.

NIT 1. NIT 6's test checks only a value use inside a plain function (tests/test_readme_windows_quoting_sentence.py:643-658). Two one-line mutants of calls_to at :554 leave the file green (44 passed each):

• Builders stop counting. host_values(tree, quoter_names(tree)) in place of host_values(tree, names) drops a line builder passed as a value.
  • The committed guard flags def a(ss, ds): return list(map(functools.partial(copy_command, platform=os.name), ss, ds)), next to a copy_command(s, d, platform=None) builder, as {'a'}.
  • The mutant gives set().
• Methods lose their class. function.rsplit(".", 1)[-1] in place of function names a value use in a method without its class.
  • The committed guard flags class P: def line(self, w): return ' '.join(map(shell_quoted, w)) if os.name == 'nt' else '' as {'P.line'}.
  • The mutant gives set().
• Fix: add those two sources to the test, asserting {'a'} and {'P.line'}.

NIT 2. No test prints a non-ASCII path under an emulated Git Bash or PowerShell host (tests/test_git_bash_dialect.py:248, :282).

• What rests on it. The merged README.md:163-165 and handbook.html:744-746 say such a path is written $'…' "in Git Bash". That holds because quote_arg passes quoted_beyond_ascii the windows it took from host_shell_dialect() (shape-doctor.py:919-923).
• The gap. This mutant at :923 is caught only by the one-question guard (2 failed, 261 passed):
  quoted_beyond_ascii(text, (os.name if platform is None else platform) == "nt", printed_encoding(encoding))
  No line test sees Git Bash handed ('C:\Users\Zo' + [char]0x00EB + '\work').
• Fix: one row asserting the exact spelling of doctor.quote_arg(r"C:\Users\Zoë\work", encoding="ascii") per host:
  • $'C:\134Users\134Zo\303\253\134work' for git-bash and msys2;
  • ('C:\Users\Zo' + [char]0x00EB + '\work') for powershell and empty-msystem.
  • It has to be exact text, because shlex.split cannot read $'…' back; test_785_a_value_is_spelled_for_sh does the same.

NIT 3 (optional). The handbook's cmd.exe clause (docs/handbook.html:742-744). The sentence is accurate: the probe below gives a cmd.exe outside Git Bash nt, and one inside it posix. A reader still has to infer two things:

• that a cmd.exe started inside Git Bash gets Git Bash's quoting;
• that cmd.exe does not read PowerShell's quoting once a word is quoted ('C:\my dir' reaches git as two words with the apostrophes in them).

A possible rewording: "so a PowerShell or cmd.exe started there is handed Git Bash's quoting. A cmd.exe started anywhere else is handed PowerShell's, which it does not read once a word is quoted, so paste those lines into PowerShell."

NIT 4 (optional). One stale word in a docstring (shape-doctor.py:867, in #792's paragraph of quote_arg's docstring). "On Windows that is rare" speaks of the PowerShell expression. Since the merge, Git Bash is on Windows too and takes the sh branch. "In PowerShell that is rare" says what it means.

Checked and true

• README and handbook match the code at 4ed7d2e0. A probe emulated seven hosts by swapping the os that repo_shape.host_shell_dialect and setup's copy read: PowerShell, cmd.exe, Git Bash, a cmd.exe inside Git Bash, nt with an empty MSYSTEM, POSIX, and POSIX with MSYSTEM.
  • nt is answered only on nt with no non-empty MSYSTEM.
  • quote_arg, shell_quoted and setup's shell_word agree on every host: 'C:\Users\Jane O''Neill\work' in PowerShell and cmd.exe, 'C:\Users\Jane O'\''Neill\work' in Git Bash and in a cmd.exe started inside it.
• The sentence's list is exact. family.py asks the host at :804 (switch -c), :1654 (NEXT), :1865 (add), :2825 (cd) and :4553 (git rm -r --cached). Setup's family_next_command quotes for the host. hand_over's cd (:2821) and finish_by_hand are posix=True and are not family lines. No doctor line forces posix.
• shape-doctor.py: a path that is not ASCII is printed as that path in every NEXT, keep line and WHY, as itself where the report's encoding writes its bytes and escaped whole where it does not, so a line naming Projets/Équipe or a Latin-1 name runs as printed (#785) #792 composes with repo_shape.py and the tools that print paste lines: under Git Bash (MSYSTEM set) the host-quoted lines are quoted for sh, not PowerShell, so a pasted NEXT line works in the shell that printed it (#532, option (a)) #711 as the writer's table says.
  • With an ASCII report, PowerShell and cmd.exe get ('C:\Users\Zo' + [char]0x00EB + '\work'), and Git Bash and POSIX get $'C:\134Users\134Zo\303\253\134work'.
  • bash reads the latter back to the path's UTF-8 bytes (checked with od).
  • With a cp1252 report, PowerShell shows the path as itself and Git Bash escapes it.
  • The import keeps both names. quote_arg keeps shape-doctor.py: a path that is not ASCII is printed as that path in every NEXT, keep line and WHY, as itself where the report's encoding writes its bytes and escaped whole where it does not, so a line naming Projets/Équipe or a Latin-1 name runs as printed (#785) #792's text = str(value) and its branch, with repo_shape.py and the tools that print paste lines: under Git Bash (MSYSTEM set) the host-quoted lines are quoted for sh, not PowerShell, so a pasted NEXT line works in the shell that printed it (#532, option (a)) #711's windows.
  • Main brought no new dialect choice: the new os.name read is git_bytes (:5579).
• The resolution is tested.
  • R1 (main's os.name line) is killed by 8 tests: test_git_bash_dialect.py and the guard.
  • R3 (no non-ASCII branch) is killed by 66, and R4 (ascii_text first) by 51, all in test_doctor_non_ascii_paths.py.
• The merge is only the resolution.
  • git diff d7befb91 4ed7d2e0 touches only repo_shape.py and the tools that print paste lines: under Git Bash (MSYSTEM set) the host-quoted lines are quoted for sh, not PowerShell, so a pasted NEXT line works in the shell that printed it (#532, option (a)) #711's 12 files.
  • In 8 of them the -U0 changed lines equal repo_shape.py and the tools that print paste lines: under Git Bash (MSYSTEM set) the host-quoted lines are quoted for sh, not PowerShell, so a pasted NEXT line works in the shell that printed it (#532, option (a)) #711's own net change (b9b70692..e15c237b). They differ only in the three resolved files and 711.txt.
  • Every other path equals git merge-tree --write-tree e15c237b d7befb91's automatic result, setup-project.py included.
• Cap. The cap test prints README.md is 1478 lines; the cap is 1422 + … + 2 (711.txt) + 2 (785.txt) + 1 (786.txt) = 1479. Main prints 1476 against 1477.
• README text. README.md:163-165 is docs-wording.md section 4 word for word, and no line is over 79 columns.
• Markers. The repository's own helpers agree:
  • readme_fingerprint(readme_segments(...)) gives e0d2b672 at 4ed7d2e0, 3d4a01ff at main and 4c523ffe at e15c237b.
  • handbook_marker_problems returns [] at all three.
  • The seven markers are at :475 :615 :1095 :1132 :1195 :1451 :1750.
  • test_the_handbook_follows_the_readmes_outline passes.
• Other docs still agree. AGENTS.md:271 ("A next with $'…' needs bash or zsh, not sh") names no host, so it is still true. No other doc ties the quoting to Windows.
• NIT 6 holds.
  • The new test fails without the fix (return called: :657, set() == {'a'}). The <module>-naming mutant is killed too.
  • On the 25 shipped tools at 4ed7d2e0, no file's builders, uses or skips change, and none hands a quoter on as a value.
• Landing texts. The 04:08 title, PR body and squash message state the merged facts: e0d2b672, +2, 1476 → 1478, cap 1479, "a cmd.exe started anywhere else", shape-doctor.py: a path that is not ASCII is printed as that path in every NEXT, keep line and WHY, as itself where the report's encoding writes its bytes and escaped whole where it does not, so a line naming Projets/Équipe or a Latin-1 name runs as printed (#785) #792's quote_arg. The body's 93 / +4 / +4 test counts and its git_bytes claim re-measure true.
• Later mains merge clean. merge-tree of 4ed7d2e0 with main 0905eef5, d6475f96 and 3bf2d3c9 is clean, and the core tests pass on each merge: 1212 passed and 3 skipped, 564 passed, and 705 passed and 1 skipped.
• Runs: the brief's set, 113 files, gives 7995 passed and 6 skipped at 4ed7d2e0, and 7894 passed and 6 skipped in 112 files at main d7befb91. The difference is exactly the 101 new tests the body claims.

Could not verify

• No real Windows host: nothing ran in PowerShell, cmd.exe or Git Bash.
• That a PowerShell or cmd.exe started from inside Git Bash inherits MSYSTEM. It is the docstring's and the handbook's premise, and it is not run here.

Lane: openreposhape-2 (openRepoShape-2)

[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

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