Skip to content

tests: a tests-git-bash job runs the launcher's and install.sh's suites in Git for Windows' own bash, so README and the handbook say Git Bash runs the one-line install, tested in CI but for a typed yes, which it cannot take there (#585) - #596

Merged
brettheap merged 26 commits into
mainfrom
fix/585-git-bash-windows
Oct 15, 2026
Merged

tests: a tests-git-bash job runs the launcher's and install.sh's suites in Git for Windows' own bash, so README and the handbook say Git Bash runs the one-line install, tested in CI but for a typed yes, which it cannot take there (#585)#596
brettheap merged 26 commits into
mainfrom
fix/585-git-bash-windows

Conversation

@brettheap

@brettheap brettheap commented Oct 15, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

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

What changed and why

Fix round 7: main after #598 (3fb21d9) (head 52524fe). Lane 3's #598 (#595) landed on main as 3fb21d9. It rewrote README step 3's install.sh paragraph and the handbook's masthead and start for uv, and for the two readinesses install.sh now ends with. It also changed install.sh and tests/test_install_sh.py, and added tests/test_install_sh_filter_repo.py. One merge commit, 52524fe, merges main 396c0ff: 55faad2 (#591), fbbbc8d (#572), 7fdec0a (#624), 3fb21d9 (#598) and 396c0ff (#570). No other change.

  • Conflicts. README.md had 1 region (step 3's install.sh paragraph). docs/handbook.html had 8: the consent rules' install.sh item and the seven § Starting markers. tests/test_install_sh.py merged as text, and so did the handbook's masthead and start.
  • The head holds all of main. git merge-tree --write-tree 52524fe3 origin/main gives 52524fe's own tree, 6d8ffea5. git diff --stat origin/main 52524fe3 names only this PR's six files (436+, 147-).

The README and handbook resolution with #598 (52524fe).

Fix round 6: retarget to main after #587 (22eacee) (head 4c3b72a). #587 squash-landed on main as 22eacee at 2026-10-15T20:27:52Z, and GitHub retargeted this PR to main. 22eacee's tree, 831e71db, is git merge-tree --write-tree 2b6dbb78 3d8fa05e: main holds exactly #587's final head 3d8fa05. So this round adds two merge commits and no other change:

The README and handbook resolution with #588 (3080ac0). #588 ends README's "Windows, natively" and the handbook's Windows panel with one sentence: "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." That sentence now follows this PR's Git Bash sentences, word for word. tests/test_readme_windows_quoting_sentence.py holds the handbook to README's words, and it passes.

Fix round 5 (head fe58d66). One comments-only commit to tests.yml, for the re-review's N1 and N3. The header says the FULL suite runs on Linux only, so read alone it stays true beside the exception. The job's comment gives the measured "about a minute and a half (86 s on the first run, 50 s of it pytest)" where it said about three minutes.

Fix round 4 (head 5f001de). Brett Heap merged #597 ("ci: run the test suite on Linux only") at 2026-10-15T16:54:43Z, which removed the Windows job these suites ran in. His word at 2026-10-15T18:20:35Z: "Option 1: keep a small Git Bash job for #596". That round added two commits:

v1.0.1's one-line install (#564) is meant to work in Git Bash on Windows, but nothing ran it there: tests/test_openreposhape_command.py and tests/test_install_sh.py wore WINDOWS_SKIP. They now run in the tests-git-bash job, under Git Bash.

Which bash. BASH in tests/conftest.py is Git for Windows' usr\bin\bash.exe, found from git --exec-path, never from PATH. Probe 1 on windows-latest showed why:

  • A bare bash through subprocess is System32's WSL launcher. It prints "Windows Subsystem for Linux has no installed distributions." in UTF-16. CreateProcess searches System32 before PATH.
  • shutil.which("bash") finds Git\bin\bash.EXE. That launcher puts Git's mingw64\bin and usr\bin first on PATH, so Git's real curl came before the suite's fake one. The old install.sh suite, run that way, reached github.com and printed the real newest release: release: v1.0.1, the newest release of opensoft/openRepoShape (https://github.com/opensoft/openRepoShape/releases/latest).

A git_bash_session fixture puts Git's mingw64\bin (or clangarm64\bin on ARM64), usr\bin and MSYSTEM where Git Bash puts them, behind any fake a test puts first. BASH_SKIP replaces WINDOWS_SKIP in these two files only.

What the tests now do on Windows.

  • Paths. Every path handed to bash, or expected in what it prints, is spelled the way Git Bash spells it (/d/a/...). The conversion uses Git's own cygpath (bash_path, native_path). Git Bash converts HOME, TMPDIR and PATH itself.
  • Line endings. Every script a test writes for bash is written as LF bytes. The fake's redirect headers and its gh tag are written as bytes: Python on Windows prints \r\n, and $(...) keeps the \r.
  • The executable bit. Git Bash's drives are mounted noacl, so chmod 755 changes nothing. A file that starts with #! runs anyway. --install's output is checked by mode 755 on POSIX, and by bash's own test -x on Windows.
  • A test's own PATH. On Windows it holds #!/bin/sh wrappers. A symlink to a Git Bash program cannot load its DLL: with symlinks, mktemp failed and install.sh refused could not make a temporary directory.
  • An argument holding a newline reaches Git Bash through the environment. On the Windows command line it was split in two: v1\nforged arrived as "two versions given". In Git Bash, bash hands bash the argument whole, so the test now does the same.
  • ln -s. A new test makes a link with Git Bash's own ln -s, after dropping any $MSYS the caller set. By default that is a copy, which has no openRepoShape.ref beside it and so follows main. With MSYS=winsymlinks:nativestrict it is a real link, which reads the record.
  • Two anchors (fix round 2).
    • The fetched-setup.sh test now also asserts that the parent of the stub's directory exists. Its "the directory is gone" line therefore cannot pass on a path Python cannot open. Both asserts read one ran_dir = native_path(ran_in) (fix round 3), so the existence check cannot be reverted to Path(ran_in) alone.
    • The gh shim test already could not pass with the shim unreachable: it asserts that the shim's own log holds exactly auth status, and only the shim writes that log. Probe 4 reverted its os.pathsep and it still passed: the shim stayed reachable either way, most likely through MSYS's conversion of PATH, which the log does not show.

The workflow (fix round 4).

The docs.

Decisions and their evidence

  • A separate small job, on Brett Heap's word. At 2026-10-15T18:20:35Z he chose "Option 1: keep a small Git Bash job for tests: a tests-git-bash job runs the launcher's and install.sh's suites in Git for Windows' own bash, so README and the handbook say Git Bash runs the one-line install, tested in CI but for a typed yes, which it cannot take there (#585) #596". The option read: "A small Windows job for just these two suites. The probe runs took 2-3 minutes end to end, so it finishes well inside the 34-36 minute Linux job and adds no wall-clock time. The README claim stays true. It is an exception to ci: run the test suite on Linux only #597's decision, so it needs your word." So the job runs these two suites and nothing else. It is not a matrix entry on the ubuntu job, whose actionlint download is a linux-amd64 binary.
  • Every trigger, a push to main included. A squash lands a tree no pull-request run tested (tests.yml runs on pull_request only, so main itself is never tested after a squash — a push-to-main trigger is a CI-minutes decision for Brett #122), and these two suites are the only run of the one-line install on Windows. At about a minute and a half beside the ubuntu job (86 s on its first run), it adds no wall-clock time.
  • What the job keeps from the old Windows job, and why.
  • What it leaves out.
    • git-filter-repo. These suites never reach a real one. The install suite's PATH holds only its own fakes, git-filter-repo and pipx among them. The launcher's machine report gets a fake git-filter-repo on the PATH machine_path builds. On Linux, with every PATH directory that held a git-filter-repo removed (filter-repo=none in the run log), the two suites gave 113 passed. test_it_installs_the_git_filter_repo_ci_runs still finds the ubuntu job's pin.
    • actionlint. The ubuntu job lints this file.
  • usr\bin\bash.exe, not bin\bash.exe, and not PATH. The probe-1 lines quoted above.
  • git_bash_session is needed, though the runner's own PATH hides it.
    • The runner's PATH already holds Git's bin, usr\bin and mingw64\bin, with bin before System32 (probe-1 PATH dump). So reverting the fixture changes nothing there (probe 2: 113 passed).
    • A stock Git for Windows install puts only Git\cmd on PATH. Probe 3 ran the two files on exactly that PATH, where which mktemp is None and which bash is C:\Windows\system32\bash.EXE:
      • with the fixture: 113 passed;
      • with it reverted: 59 failed, 15 passed, 39 errors, for example bash: line 199: mktemp: command not found and this machine has no mktemp, which the install needs.
  • bash -s runs still take their script through a text-mode pipe. That pipe hands bash CRLF on Windows, but Git Bash's bash drops a carriage return before a newline: a CRLF script piped to it printed crlf-ok and exited 0 (probe 1). Sending bytes instead changed no result (mutation text-stdin, 113 passed), so that change was dropped.
  • Python can make symlinks on the runner (os.symlink: ok), so the three existing symlink tests run there unchanged.
  • The macOS sentence names Git Bash without a line. "No CI run, on Linux or in Git Bash on Windows, checks them against bash 3.2" is true with this job, and fits README's four lines. A clause naming the two suites would have needed a fifth line and a cap raise.
  • Not claimed: that setup's own yes is asked in Git Bash. Typed at a Git Bash prompt, openRepoShape <Project> reads its yes through native Windows Python. Whether that Python sees a console depends on Git Bash's pseudo-console support, and nobody has confirmed it on a Windows machine.

Tests

  • Linux, on the head 52524fe (fix round 7, dirty=0):
  • actionlint 1.7.12 on 52524fe, on tests.yml and the two template workflows: exit 0, with shellcheck on PATH. tests.yml is the same blob as at 4c3b72a (5fc46de7); install.sh: git-filter-repo with the uv already there where there is no pipx, never pip install --user, and two readinesses at the end, adoption: then done: (#595) #598 does not touch it.
  • Linux, on the head 4c3b72a (fix round 6, dirty=0):
    • the two suites: 113 passed in 28.57s;
    • tests/test_repo_hygiene.py, tests/test_readme_sections.py, tests/test_cli_reference.py, tests/test_setup_by_hand_commands.py and tests/test_readme_windows_quoting_sentence.py: 171 passed in 17.09s.
    • Those cover every tests/test_install_sh*.py (there is one) and every test file git grep -l 'install.sh' tests/ finds (test_install_sh.py, test_repo_hygiene.py; the other two hits are conftest.py and readme-cap.d/564.txt).
    • 3080ac0's merge, before its commit: test_repo_hygiene.py, test_readme_sections.py and test_readme_windows_quoting_sentence.py, 144 passed.
  • actionlint 1.7.12 on 4c3b72a, on tests.yml and the two template workflows: exit 0, with shellcheck on PATH. The workflow keeps main's .github/workflows/tests.yml: a push run on main is grouped by its commit, so the next landing no longer cancels it, and every landing gets its own Linux result (#592) #593 concurrency block byte for byte (this PR's two tests.yml hunks are the header and the new job), the header's "The FULL suite runs on LINUX ONLY" with the exception sentence, and tests-git-bash.
  • Linux, on the head 5f001de (dirty=0): the two suites, tests/test_repo_hygiene.py, tests/test_readme_sections.py, tests/test_cli_reference.py and tests/test_setup_by_hand_commands.py: 281 passed in 61.24s.
  • Linux, fix round 4, before its commit:
    • the two suites: 113 passed;
    • the two suites with no git-filter-repo on PATH: 113 passed;
    • the four docs and hygiene files: 168 passed;
    • the merge alone, before its commit: test_repo_hygiene.py and test_readme_sections.py, 141 passed.
  • actionlint 1.7.12, fetched and checksum-checked as the ubuntu job does, on tests.yml and the two template workflows: exit 0, with shellcheck on PATH.
  • The YAML parse. Triggers: push to main, pull_request, workflow_dispatch. Jobs: tests (ubuntu-latest) and tests-git-bash (windows-latest, timeout-minutes: 15). Neither has an if:, so both run on every trigger.
  • Linux, earlier rounds: on 01e8c2c, the same five files without test_setup_by_hand_commands.py, 276 passed. Lane 5's re-review got the same 276 there. On 649b089, with tests/test_setup_by_hand_commands.py, tests/test_agents_md_codes.py and tests/test_gh_guard.py as well, 334 passed.
  • Windows, windows-latest, through probe branches that ran only these suites:
    • Probe 1 (run 38752845751): 109 passed, 2 failed, 0 skipped. The two failures were the newline arguments, fixed since.
    • Probe 2 (run 38754067543, tree ebba347): 113 passed, 0 skipped, in 68.83s.
    • Probe 3 (run 38757083883, on 649b089): 113 passed in 50.97s. On a stock Git for Windows PATH (only Git\cmd): 113 passed.
    • Probe 4 (l5-585-probe-4, on 01e8c2c): 113 passed in 77.92s (run 38769166462).
  • The same two files as they were at 5191f0e, with only WINDOWS_SKIP lifted (probe 1): 88 failed, 23 passed. Two causes: the WSL launcher, and the real network through Git\bin\bash.EXE.
  • Windows on 5f001de, the PR's own run of tests-git-bash: 113 passed in 50.28s, with the whole job taking 1 min 26 s (18:37:00Z to 18:38:26Z, check run 116601758252).
    • The guard step printed C:\Program Files\Git\usr\bin\bash.exe.
    • Its steps and env are probe 4's, less the git-filter-repo install, and with -q -rA and a 15-minute job timeout.

Mutation probes

Probe 2 ran these on ebba347, the tree before the squash, which still had a run_piped helper; the text-stdin row is that helper. The squashed head 649b089 was then re-measured whole by probe 3 (113 passed), and fix round 2's head 01e8c2c by probe 4. Each row reverts one Windows hunk and runs the two files again.

Hunk reverted Result
BASH is the bare word bash 108 failed
paths keep Windows' spelling 25 failed
scripts written with write_text (CRLF) 1 failed: test_a_release_whose_command_records_no_ref_exits_one, whose launcher's first line became #!/usr/bin/env bash\r and was refused as not the command
the fake prints its headers and tag in text mode 22 failed
mode 755 checked on Windows too 2 failed
symlinks on a test's own PATH 28 failed
newline arguments on the command line 2 failed
no git_bash_session 113 passed on the runner's PATH; on a stock Git for Windows PATH (probe 3) 59 failed and 39 errors, against 113 passed with it
bash -s script sent as bytes (run_piped) 113 passed either way; this hunk was dropped

Fix round 2's anchors (probe 4, on 01e8c2c):

Run Result
the fetched-setup.sh test, native_path(ran_in) reverted to Path(ran_in) in both asserts exit 1: 1 failed. The new parent-directory anchor catches it. Since fix round 3 both asserts read one ran_dir, so this is the only way to revert it.
the gh shim test, its PATH joined with : instead of os.pathsep exit 0: 1 passed. The shim stays reachable, so the hunk is not load-bearing on this runner. The log shows only that outcome; MSYS's conversion of PATH is the likely reason. The test is still not vacuous: it asserts that the shim's own log holds exactly auth status, and only the shim writes that log, so an unreachable shim would fail it.
both ln -s cases with MSYS=winsymlinks:nativestrict exported, head exit 0: 2 passed
the same, with the MSYS drop reverted exit 1: 1 failed (ln-default made a link), 1 passed

With lane 3's #590 (l3-563-pypi-package): the second to land converts four cases, and resolves tests.yml

#590 adds four cases to these two suites, written while they skipped on Windows:

  • test_a_command_that_is_a_symlink_is_refused_before_any_request[live|dangling];
  • test_install_refuses_a_target_that_is_a_symlink[live|dangling].

Each compares a path bash printed with str(path). Each also compares os.readlink's answer with the target, and on Windows that answer typically starts \\?\ (Python's os.readlink documentation, since 3.8; the probe's failures stop at the first assert, so no log shows it). Linux passes on the merged tree (117 passed), but under Git Bash those four cases fail, and tests-git-bash runs them.

Whichever of #596 and #590 lands second applies these hunks to the merged tree. Probe 4 (run 38769166462) applied exactly these.

--- a/tests/test_install_sh.py
+++ b/tests/test_install_sh.py
@@ -668,12 +668,14 @@ def test_a_command_that_is_a_symlink_is_refused_before_any_request(
     result = net.run()
     assert result.returncode == 2, result.stdout + result.stderr
     said = " ".join(result.stderr.split())
-    assert f"{link} is a symbolic link, so nothing was installed" in said, said
+    assert f"{bash_path(link)} is a symbolic link, so nothing was installed" \
+        in said, said
     assert "pipx upgrade openreposhape" in said
     assert "pipx uninstall openreposhape" in said
     assert net.calls() == [], net.calls()
     assert link.is_symlink()
-    assert link.readlink() == packaged
+    # Windows reads a link back with `\\?\` ahead of its target.
+    assert str(link.readlink()).removeprefix("\\\\?\\") == str(packaged)
     if not dangling:
         assert packaged.read_bytes() == original
     assert sorted(path.name for path in net.bin.iterdir()) == \
--- a/tests/test_openreposhape_command.py
+++ b/tests/test_openreposhape_command.py
@@ -407,17 +407,18 @@ def test_install_refuses_a_target_that_is_a_symlink(tmp_path, dangling):
     link = bin_dir / "openRepoShape"
     link.symlink_to(packaged)
     result = run_cmd("--install", home=tmp_path,
-                     env={"OPENREPOSHAPE_BIN_DIR": str(bin_dir),
+                     env={"OPENREPOSHAPE_BIN_DIR": bash_path(bin_dir),
                           "OPENREPOSHAPE_REF": "v9.9.9",
                           "OPENREPOSHAPE_RECORD_REF": "1"})
     assert result.returncode == 2, result.stdout + result.stderr
     said = " ".join(result.stderr.split())
-    assert f"{link} is a symbolic link, so --install will not copy this " \
-        "command through it" in said, said
+    assert f"{bash_path(link)} is a symbolic link, so --install will not " \
+        "copy this command through it" in said, said
     assert "pipx upgrade openreposhape" in said
     assert "pipx uninstall openreposhape" in said
     assert link.is_symlink()
-    assert os.readlink(link) == str(packaged)
+    # Windows reads a link back with `\\?\` ahead of its target.
+    assert os.readlink(link).removeprefix("\\\\?\\") == str(packaged)
     if not dangling:
         assert packaged.read_bytes() == original
     assert not packaged.with_name("openRepoShape.ref").exists()

Both files already import bash_path once #596 is in. On Linux, the merge of 649b089 with d090f0c, with these hunks: 117 passed. Fix round 7, on the merge of 52524fe with #590's head 1c8a708, with fix round 6's resolved tests.yml (both inputs unchanged since; the result is blob 266c62c7): the hunks apply (git apply --check exit 0). The two suites (117 by collection), tests/test_install_sh_filter_repo.py (18), tests/test_openreposhape_package.py and tests/test_repo_hygiene.py give 270 passed in 48.69s. Fix round 6: on the merge of 4c3b72a with #590's current head 1c8a708, with tests.yml resolved as below, the hunks apply (git apply --check exit 0) and the two suites give 117 passed; with tests/test_openreposhape_package.py and tests/test_repo_hygiene.py, 252 passed. Probe 4 runs the merge of 01e8c2c with l3-563-pypi-package on Windows: the four cases without the hunks, then both suites with them. In run 38769166462, on Windows:

  • Without the hunks: exit 1, 4 failed, 113 deselected. These are exactly the four cases. The launcher pair failed on REFUSED: D:\a\_temp\…\bin/openRepoShape is a symbol…, which confirms rv585's inferred launcher failures; the install pair failed on REFUSED: /d/a/_temp/…/.local/bin/openRepoShape ….
  • With the hunks: they apply (exit 0), and both suites give 117 passed in 75.13s.

tests.yml conflicts with #590 (fix round 6; unchanged in fix round 7, where #590's head is still 1c8a708 and this PR's tests.yml is the same blob). #590 now targets main too: at fix round 6 its merge ref's first parent was main 77bb5f0. Its head 1c8a708 has merged #587's final head and main, so it holds #597, and it merges with main cleanly. Both PRs add to the same two places in tests.yml, so against 4c3b72a there are three regions:

Merge checks (git merge-tree --write-tree, head 52524fe)

The open pull requests are the 17 with a refs/pull/<n>/merge ref in git ls-remote origin 'refs/pull/*': 583, 590, 594, 596, 599, 614, 617-623 and 625-628. Each head was merged with 52524fe and, separately, with main 396c0ff. The ones not in the table merge cleanly with this head and touch none of its six files: #583, #614, #617, #618, #619, #621, #622, #625, #626 and #628.

Against Result
origin/main 396c0ff (#591, #572, #624, #598 3fb21d9, #570) clean. The merge gives this head's own tree, 6d8ffea5: the head holds all of main.
#590 1c8a708 (l3-563-pypi-package) conflicts in .github/workflows/tests.yml, 3 regions: the header and the end of the jobs. #590 against main alone is clean, so this is the two PRs' own overlap. It also touches tests/test_install_sh.py and tests/test_openreposhape_command.py, which merge as text. See the #590 section above for the resolution, the four test cases and fix round 7's 270 passed.
#599 b0182e2 (lane 3, stacked on #590's old head d090f0c) conflicts in .github/workflows/tests.yml, 2 regions. #599 also conflicts with main alone, in six files (tests.yml, README.md, the handbook, install.sh, openRepoShape, tests/test_install_sh.py). It is #597's conflict, through #599's stale base, not this job's.
#627 fc0656b (fix/606-readme-followups, #606; new since fix round 6) conflicts in docs/handbook.html only: 7 regions, each one § Starting marker line (this PR's badbb6b2 against #627's 51702a2b). Its README hunks (the second-run refusal in § Starting, and CONTRACTS_DIR and the single-repository.yaml question in § Adopting) merge as text with this PR's. #627 against main alone is clean. Whoever lands second sets the seven markers to the merged README's hash. On this head plus fc0656b that is fe0d932b031e4a08fc885f93d6cd978df0d5a25c. README is then 1456 lines: 1449 plus #627's own readme-cap.d/606.txt (+7).
#594 be808a7, #623 1e30fa7 clean. Both touch tests/conftest.py, which merges as text.
#620 4c049a8 conflicts in adopt-project.py, and so does #620 against main alone: its own conflict with main, not an overlap with this PR.

#598 landed as 3fb21d9 and is in the main row; fix round 7 is that merge. Every lane-5 PR and every other PR that has landed is in the main row.

For the squash message

The first commit's message says "bash -s runs keep bash as argv[0] and name BASH as the executable". That is true of the launcher's suite only. The installer's suite still passes BASH as argv[0], as before; install.sh reads neither $0 nor BASH_SOURCE. The squash message should say so; the fix-round-2 commit message already does. It should also name tests-git-bash and Brett Heap's word, and say the guard step now lives in that job. Since fix round 7 it should also say that README step 3's install.sh paragraph is reworded to hold both #598's text and the Git Bash clause at the 1449-line cap. The paragraph now opens "install.sh, attached to every release, installs the newest with no gh and no login", and says "It never runs sudo itself".

Left out, and why

For the v1.1.0 release notes (lane 3 owns the notes)

No v1.1.0 notes file exists on main yet, so this PR writes none. Proposed text, a section of its own:

Git Bash on Windows (#585). Git Bash, the bash that Git for Windows installs, runs the one-line install and the openRepoShape command. CI's tests-git-bash job runs their suites under Git for Windows' own bash, with the PATH Git Bash makes, and fails if it cannot find that bash. That job is an exception to #597's Linux-only CI, made on Brett Heap's word. In PowerShell the way in is unchanged: py setup-project.py. Two things differ from macOS and Linux. ln -s in Git Bash makes a COPY unless MSYS=winsymlinks:nativestrict is set; a copy has no openRepoShape.ref beside it, so it follows main, and openRepoShape --version says so. Link it with that setting (Windows lets a non-administrator make a symlink only in Developer Mode), or put ~/.local/bin on PATH instead. And chmod changes nothing on Git Bash's drives; a file that starts with #! runs as a command anyway. Not tested there: setup.sh run on its own (its suite still skips on Windows), and any typed yes, for which CI has no terminal. In Git Bash the preflight that the one-line install ends with cannot take a yes at all, so it installs nothing for you.

Checklist candidates

  1. The machine report's python3 line on Windows. --install's machine: block probes only python3. Where Python came from python.org, Git Bash has python and no python3, or only the Microsoft Store stub. The block then says python3 MISSING, or "present" for a stub, while --preflight passes with python.
  2. A drive-letter $OPENREPOSHAPE_REPO. shape_clone_url treats C:/src/openRepoShape as an owner/name and builds https://github.com/C:/src/openRepoShape.git from it. Git Bash and git itself both accept the drive-letter spelling.
  3. A Windows-spelled $OPENREPOSHAPE_BIN_DIR. --install then prints export PATH="D:\...:$PATH", which bash cannot use: the drive's colon splits it.
  4. A stale docstring. test_a_ref_the_doctor_would_check_out_is_validated says the refusal arrives before any clone. shape_checkout clones first, then checks the ref.
  5. On Windows, the preflight a piped install ends with cannot take a typed yes.
  6. The handbook's step 3 has no Git Bash path. Its install block and paragraph are data-platform="linux mac wsl" (docs/handbook.html:775-784 on 01e8c2c), so a reader on the Windows tab never sees the one-line install that the Windows panel says Git Bash runs. Adding it to the Windows tab is a docs decision.
  7. In Git Bash, the host-quoted lines are still quoted for PowerShell. openRepoShape --doctor, a family setup-project.py run and family.py, started from Git Bash, run under native Windows Python, where os.name is nt. So quote_arg, shell_quoted, shell_line and shell_word (for example setup-project.py:2331, if os.name == "nt" and not posix) quote for PowerShell, even though the person is at a bash prompt. bump-leg.py and update-shape.py quote the paste lines that named a root or a path bare, the doctor's quote_arg quotes a leading = for zsh, and README says the printed commands are for a POSIX shell (#532) #588's sentence stays true ("on Windows"). But someone who follows "Git Bash runs that command" and pastes such a line back into Git Bash gets the failure that tests/test_readme_windows_quoting_sentence.py's docstring names: git -C C:\work\Orbit reads as C:workOrbit. Choosing sh's dialect under Git Bash (for example on MSYSTEM) would be a Printed commands are POSIX-only: quote the bare paste lines in bump-leg.py and update-shape.py, and say in the docs that pasted commands are for a POSIX shell #532 decision.
  8. install.sh: git-filter-repo with the uv already there where there is no pipx, never pip install --user, and two readinesses at the end, adoption: then done: (#595) #598's installer cases do not run under Git Bash. tests-git-bash runs tests/test_install_sh.py, and since fix round 7 that suite reaches install.sh: git-filter-repo with the uv already there where there is no pipx, never pip install --user, and two readinesses at the end, adoption: then done: (#595) #598's code in two ways: every run now prints adoption: and done:, and no_pipx expects uv's printed command. But the uv install, the readinesses' wording and the pasted next steps are tested in tests/test_install_sh_filter_repo.py only, on Linux. README says Git Bash runs step 3's one line, "tested in CI".
    • What the file uses. It inherits test_install_sh.pytestmark (BASH_SKIP and git_bash_session), and drives every run through Net: fake (LF bytes through write_script), run (BASH, bash_path(INSTALLER)), serve, installed and calls. Its own uv fake writes LF bytes, like Net.fake, and names the interpreter as shlex.quote(sys.executable), as Net.fake does in the job today. No assert compares a path bash printed with a Python path; each checks a line's start or end.
    • Under Git Bash it would likely pass. Its programs see PATH=net.path alone, so the runner's own pipx or uv cannot leak in. The launcher's --install probes python3 with command -v and never runs it, so the logging python3/python fakes stay silent. Its paste() sends a script through a text-mode pipe, as Net.run(piped=True) already does in the job.
    • Not run on Windows. On Linux: 18 passed in 7.32s. Adding it to the job is one more path on the job's pytest line.
  9. README still names pip install git-filter-repo for adopting. README:768 (§ Adopting) says "git filter-repo is a hard dependency — pip install git-filter-repo, or the same name from apt or brew." Installer: support uv for git-filter-repo and distinguish adoption readiness from general readiness #595 found that pip install is refused on an externally managed Python (Debian 12, Ubuntu 23.04, Arch; PEP 668), and install.sh: git-filter-repo with the uv already there where there is no pipx, never pip install --user, and two readinesses at the end, adoption: then done: (#595) #598's install.sh no longer prints it. Neither install.sh: git-filter-repo with the uv already there where there is no pipx, never pip install --user, and two readinesses at the end, adoption: then done: (#595) #598 nor this PR touches that line.

Closes #585

🤖 Generated with Claude Code

Brett Heap and others added 13 commits October 14, 2026 23:34
Brett Heap @claude
openRepoShape: --install records the ref it runs at in `openRepoSha…
026280c 
…pe.ref` beside the command it places, and the installed command then fetches setup.sh at that ref, hands setup.sh `--shape-ref` for it and checks the doctor's clone out at it, so a command installed from a release stays on that release while `$OPENREPOSHAPE_REF` still overrides it for one run (#564)

An installed command read `$OPENREPOSHAPE_REF` at every run and fell back
to main, so from v1.0.0 on, with main carrying v1.1.0 work, a command
installed from a release drifted off it within hours. The ref is now NAMED
by the variable or by the record, and both places that honoured only the
exported variable (the doctor's checkout and setup.sh's `--shape-ref`)
honour either.

The record is a sidecar file, never an edit to the command: the placed
command stays byte for byte the file it was installed from, so the
installer's own `(unchanged)` verdict and any copy vendored and checked by
sha256 still compare bytes and never see the record. An install with no
ref records nothing and removes any record already there, which is the
command exactly as before. The ref is checked before anything is placed,
and the record is checked when it is read, naming the file and the two
ways out. `--version` prints the ref in force. docs/cli.md is regenerated
for the `--help` paragraph that says so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brett Heap @claude
install.sh: one line, `curl -fsSL https://github.com/opensoft/openRep…
d0cdbf4 
…oShape/releases/latest/download/install.sh | bash`, installs the newest release's openRepoShape pinned to that release, installs git-filter-repo with pipx where pipx is and it is not or prints the one command that would, and ends with `openRepoShape --preflight`; README, the handbook and the v1.0.1 release notes lead with it (#564)

Brett Heap, 2026-10-14: "we need it to be more simple to install ... now
and after, we need a simple install process", and "v1.0.1 soon".

install.sh is attached to every release, so `releases/latest/download/`
is always the newest. It reads the newest tag from github.com's
`releases/latest` redirect with no gh and no login, asking `gh api` only
when the redirect names none; takes a named release as its one argument;
fetches that release's `openRepoShape`, checks it is the command, and runs
its `--install` with `$OPENREPOSHAPE_REF` set to the release, then asks the
installed command's `--version` that it stayed there. Every step says what
it did in one line. It never runs sudo. Exit 0 installed and ready, 1
installed but the preflight or the pin needs attention, 2 nothing
installed; git-filter-repo never moves it. Everything runs from a `main`
called on the last line, so a cut-off download runs nothing.

README.md: step 3 and the worked example lead with the one line, the gh
api and raw-URL lines stay as the by-hand way at main, and Layout gains
install.sh; the cap moves 1422 -> 1450, with the reason in
test_readme_is_short_enough_to_be_read. docs/handbook.html says the same,
names the new README blob and adds the (#564) clause. install.sh joins
SHIPPED_BASH and the macOS job's `/bin/bash -n` step, and one test holds
the one line byte for byte in every file that carries it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brett Heap @claude
openRepoShape and install.sh, the fix round on #577: --install reco…
319b005 
…rds a ref only with `OPENREPOSHAPE_RECORD_REF=1`, which install.sh sets, so a script that exports `$OPENREPOSHAPE_REF` around it gets v1.0.0's install; every curl that runs is HTTPS only, redirects included, at TLS 1.2 or newer; a link to the command reads its record; `--help` answers past a broken record; and install.sh says which failure it met (#564)

The review on #577 (RV577, FIX-ROUND) and SonarCloud shell:S6506.

openRepoShape:
- The ref is recorded only when asked, or when it came from the command's
  own record (a re-install of itself stays pinned). workBenches exports
  `OPENREPOSHAPE_REF=pinned-by-workBenches-no-fetch` around `--install`;
  that no longer becomes a record every later run would fail on. Any other
  install records nothing and removes a record already there.
- The raw-URL fallback curl carries `--proto '=https' --proto-redir
  '=https' --tlsv1.2`, written on the line.
- The record is found beside the FILE, symlinks followed with a portable
  `readlink` loop (no `-f`, at most 40 links).
- A broken record is kept as a fault and refused after the arguments are
  read, so `--help` still answers; `--version` and every run refuse. A
  record that is a directory is refused in the usual form, by a run and by
  an install, before anything is placed.

install.sh:
- Both curls HTTPS only, redirects included, TLS 1.2 or newer.
- Sets `OPENREPOSHAPE_RECORD_REF=1` for the install.
- A fetch the server refused (curl exit 22) asks whether the release
  exists; no answer at all points at the network instead. A preflight that
  exits 1 names what is missing; any other status says it did not run to
  the end.
- With no pipx, `apt-get` machines are told `sudo apt-get install -y pipx
  && pipx install git-filter-repo==2.47.0` (printed, never run), because
  Debian 12 and Ubuntu 23.04+ refuse `pip install --user`.
- A command that did not record the tag gets its preflight run with the tag
  named, not main's setup.sh; the shell-profile notes say so.
- The last line is `{ main ${1+"$@"}; }`: a download cut inside it runs
  nothing. install.sh itself never runs sudo; the wording now says the
  preflight's offers, some of them sudo, each wait for a typed yes.

Tests: HTTPS_ONLY in the call asserts and a guard on every curl that runs
in both scripts; the opt-in, links, a directory record and `--help` past a
bad record; an upper-case and a relative `location`; a non-default
OPENREPOSHAPE_BIN_DIR; the apt-get branch; the network failure; the
preflight's two failures; three truncated downloads; S9073 composite
asserts split. docs/cli.md regenerated for the `--help` change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brett Heap @claude
README.md, docs/handbook.html, AGENTS.md and the v1.0.1 release notes…
322a305 
…, the fix round on #577: install.sh itself never runs sudo while the preflight it ends with offers what is missing behind a typed yes, the command is pinned to the release tag only when asked, step 3 folds the pin into one paragraph six lines shorter, AGENTS.md says the one-line install is the human's to run, and the notes gain the steps that attach install.sh to the release (#564)

- README.md: step 3's paragraph now carries what "pinned" means and the
  corrected sudo sentence, and leaves the exit statuses to `install.sh
  --help` and the release notes; the worked example's lead-in is one line.
  The cap moves to 1444 (from 1450 in d0cdbf4), with the reason updated in
  test_readme_is_short_enough_to_be_read.
- docs/handbook.html: the same paragraph, the same rule in "For AI
  assistants", the #564 footer clause updated, and the new README blob.
- AGENTS.md: "The one-line install (`install.sh`) is theirs to run: relay
  it, never run it." under "Never answer an install prompt", paid for by
  tightening the `--allow-upstream-org` paragraph's middle clause; still
  490 lines, every rule kept.
- docs/release-notes/v1.0.1.md: the corrected sudo sentence, the opt-in
  (`OPENREPOSHAPE_RECORD_REF=1`) and what a script that exports
  `$OPENREPOSHAPE_REF` now gets, HTTPS only, Git Bash supported but its
  tests skip on the Windows job (a known limit, followed up in v1.1.0), and
  a "Before tagging (remove at tag time)" section: upload install.sh to
  v1.0.1, check the `releases/latest/download/install.sh` redirect, never
  attach it to v1.0.0, and publish a later patch on an older line with
  `--latest=false`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brett Heap @claude
docs/release-notes/v1.0.1.md: the "Before tagging" steps are safe to …
868c9bf 
…follow in order (land, prove the squash tree or dispatch the three-OS run on it, tag it annotated, create the release with install.sh attached and --verify-tag, check the asset by redirect and by bytes), Git Bash is said to be meant to work but untested until #585, and only install.sh's own downloads are said to be HTTPS only (#564)

The second fix round on #577 (RV577). The old checklist published before
attaching install.sh, could tag main through `gh release create` with no
tag, uploaded an unchecked working-tree file and never tested the release
commit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brett Heap @claude
Merge remote-tracking branch 'origin/l3-564-one-line-install' into l3…
892a041 
…-564-carry-to-main

Conflicts, both resolved to main's side, because main retired the
mechanism #577's side used (#519, #551):
	tests/test_repo_hygiene.py: README.md's cap stays README_CAP_BASE plus
	  tests/readme-cap.d/; #577's inline 1422 -> 1444 raise is not taken here
	  and becomes a ledger file of its own in the next commit.
	docs/handbook.html: the footer keeps main's frozen history and its
	  closing sentence; #577's "added (#564)" clause and whole-README blob
	  are the retired convention, and the sections' markers carry it instead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brett Heap @claude
tests/readme-cap.d/564.txt: README.md's cap is 1449, raised by 22 for…
b2f0be3 
… the one-line install in a ledger file of its own, as main raises it, rather than #577's inline 1422 -> 1444 on release/v1.0 (#564)

README.md on main is 1427 lines at its cap (1422 + 5, #550); #564's lines
take it to 1449. The reason is #577's, carried with its accounting:
ten lines for the two install.sh blocks, nine for step 3's paragraph,
two for the by-hand ways kept at main, one for the Layout row.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brett Heap @claude
docs/handbook.html: the consent rules say every action the tool OFFER…
68b999f 
…S is a typed yes and the one-line install asks nothing, placing the command and git-filter-repo through pipx without sudo, and the eight sections that read README.md § Starting and § Layout record #564's README after a re-read (#564)

What changed in README.md since the markers were set is #564 alone:
`git diff f6eaab7 HEAD -- README.md` equals `git diff origin/main HEAD --
README.md` (the § Starting markers were set by #579, f6eaab7), and § Layout
moved only by the install.sh row since #551 (5e59e3b) set its marker.

Re-read against the merged README, each section in full:
- masthead: its fastest path is #577's install.sh line with an accurate
  summary (newest release, pinned, git-filter-repo where pipx can, ends in
  the preflight). No change.
- start: carries #577's install step, the by-hand ways at main and "Each way
  installs". One statement was made false: "Every action that changes the
  machine or the account is a typed yes" stood a few lines below install.sh
  installing git-filter-repo with pipx unasked. It now scopes the rule to
  what the tool offers and says what the one-line install does, every fact
  quoted from README step 3. The machine: block paragraph, the preflight
  step, Run it and What setup.sh actually runs stay true as written.
- partway (the WARNING), ci (private legs), legs (the --explain line),
  doublepin (the hand-edited pin), park (openRepoTools' line, which
  --install still prints when install.sh calls it): nothing #564 touched.
  No change.
- layout: carries #577's install.sh row, in README's order; "standard
  library only" stays true (install.sh is bash, git-filter-repo a tool).
  No change.

Markers: § Starting f0693d8a -> cc78d254 in masthead, start, partway, ci,
legs, doublepin, park; § Layout c8be0af4 -> 94701efc in layout; both values
as the hygiene check printed them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brett Heap @claude
Merge remote-tracking branch 'origin/main' into l3-564-carry-to-main
53416db 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brett Heap @claude
Merge remote-tracking branch 'origin/main' into l3-564-carry-to-main
a155945 
Brings in #580 (#546), dd3f23a. One conflict:
	tests/test_repo_hygiene.py: #564's one-line-install test and #580's
	  DOCTOR_PASSAGES test were added at the same place; both are kept,
	  #564's first.
The launcher, its test, README.md, AGENTS.md, docs/handbook.html and
docs/cli.md merged cleanly, each holding both sides' hunks unchanged.
README.md stays 1449 lines (cap 1449) and AGENTS.md 490 (cap 490). Every
handbook marker of § Starting, § Layout and § Keeping equals its segment's
fingerprint in the merged README after a re-read, so none moves.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brett Heap @claude
README.md: the NOTE says the preflight installs nothing without the t…
c1e6b82 
…yped yes, beside step 3's one-line install, which installs git-filter-repo with pipx where it can (#564)

"Nothing is installed without that typed `yes`" became "The preflight
installs nothing without that typed `yes`", and the rest of the sentence is
kept. The longer clause re-wraps the NOTE's last eight lines into eight, so
README.md stays at 1449, its ledger cap, and every line stays within 80
columns. `py setup-project.py --preflight` stays on one line, because
test_the_windows_commands_name_files_that_exist reads `py <file>` across
whitespace.

Re-read against the new wording, the seven sections that read
§ Starting: start's consent rules ("Every action the tool offers ... is a
typed yes", "The one-line install asks nothing ...", "no offer at all") and
its four "The tool offers the rest" panels already put the typed yes on the
preflight's offers; its `machine:` block line is about --install, and
partway's "Nothing is created before the typed yes" quotes the WARNING, not
the NOTE; masthead, ci, legs, doublepin and park render nothing from the
NOTE. No page text changes. The markers move as the hygiene check printed:
cc78d254 -> c9aebc08 in masthead, start, partway, ci, legs, doublepin, park.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brett Heap @claude
docs/handbook.html: the consent rules say install.sh asks nothing bef…
5191f0e 
…ore its own two acts, and the preflight it ends with asks before each offer (#564)

"The one-line install asks nothing" was not true as written: install.sh
ends with `openRepoShape --preflight`, which asks `Type yes to continue:`
before each offer, as step 3 above it and README.md:239-241 say. Only
install.sh's own two acts, placing the command and installing
git-filter-repo with pipx, go unasked. Found in #587's review.

Handbook text only, in the same five lines: README.md is unchanged, so no
marker moves, and the hygiene check asks for none.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brett Heap @claude
tests/test_openreposhape_command.py and tests/test_install_sh.py run …
649b089 
…in the Windows job under Git for Windows' own bash, found beside its git and never from PATH, with paths spelled as Git Bash spells them, so the one-line install and the command it places are tested on Windows, and README and the handbook say Git Bash is supported (#585)

The two suites wore WINDOWS_SKIP, so nothing had run `install.sh` or
`openRepoShape` under Git Bash, where v1.0.1's one-line install is meant
to work. They now run there; the Windows job's PowerShell step runs them
with the rest of the suite.

tests/conftest.py:
- `BASH` is Git for Windows' `usr\bin\bash.exe`, found from
  `git --exec-path`. A bare `bash` there is System32's WSL launcher, which
  `subprocess` reaches before PATH ("Windows Subsystem for Linux has no
  installed distributions"). `bin\bash.exe`, which `shutil.which` finds,
  puts Git's `mingw64\bin` first on PATH, so Git's real `curl` shadowed the
  suite's fake one and the old install.sh suite reached github.com.
- `BASH_SKIP` replaces `WINDOWS_SKIP` in these two files only.
- `bash_path` and `native_path` convert with Git's own `cygpath`.
- The `git_bash_session` fixture puts `mingw64\bin`, `usr\bin` and
  `MSYSTEM` where Git Bash puts them, behind any fake a test puts first.
  The runner's PATH already holds both; a stock Git for Windows install
  puts only `Git\cmd` on PATH, and there `mktemp` is missing and `bash` is
  the WSL launcher.

The two test files:
- every path handed to bash or expected from it is spelled `/d/a/...`;
- every script a test writes for bash is written as LF bytes, and the
  fake's redirect headers and `gh` tag are written as bytes, because
  Python on Windows prints `\r\n` and `$(...)` keeps the `\r`;
- `bash -s` runs keep `bash` as argv[0] and name `BASH` as the executable;
- `--install` is checked as a command by mode 755, or under Git Bash, which
  keeps no mode bits, by bash's own `test -x`;
- a test's own PATH holds `#!/bin/sh` wrappers on Windows, because a
  symlink to a Git Bash program cannot load its DLL;
- an argument holding a newline reaches Git Bash through the environment,
  because the Windows command line splits it in two;
- a new test makes a link with Git Bash's own `ln -s`: by default a copy,
  which follows main, and with `MSYS=winsymlinks:nativestrict` a link,
  which reads the record.

.github/workflows/tests.yml: a step before the Windows tests fails the job
when conftest finds no Git Bash, so the two suites cannot quietly skip;
the macOS job's comment no longer says the Windows job skips the launcher.

README.md and docs/handbook.html: PowerShell has no twin of the command,
and in Git Bash the one-line install and the command are supported and
tested; WSL2 runs every bash entry point, no longer "is still how you run"
them. README keeps its line count. The seven handbook markers for
README.md § Starting a project in a new organisation record its new hash.

Lane: openreposhape-5 (openRepoShape-5)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@brettheap

brettheap commented Oct 15, 2026

Copy link
Copy Markdown
Contributor Author

(lane openRepoShape-5, 2026-10-15T15:05Z) @codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 15, 2026

Copy link
Copy Markdown

Codex Review Summary

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

Review Status Commit Review trigger
📝 Code Review ⚠️ Failed 2026-10-15T15:05:18.238403Z 649b089 Manual request
ℹ️ About Codex in GitHub

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

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

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

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 15, 2026

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

@sourcery-ai

sourcery-ai Bot commented Oct 15, 2026

Copy link
Copy Markdown

Reviewer's Guide

The PR enables and hardens the launcher and install.sh suites under Git for Windows Bash on Windows CI, adds platform-specific path, encoding, executable, PATH, argument, and symlink handling, and updates README and handbook documentation to explicitly support Git Bash.

Sequence diagram for Windows CI running tests under Git Bash

sequenceDiagram
    participant WindowsJob
    participant GitForWindows
    participant GitBash
    participant TestSuites
    participant Conftest

    WindowsJob->>GitForWindows: git --exec-path
    GitForWindows-->>WindowsJob: Git installation path
    WindowsJob->>GitBash: invoke usr/bin/bash.exe
    GitBash->>Conftest: load BASH and git_bash_session
    Conftest->>Conftest: bash_path
    Conftest->>Conftest: native_path
    GitBash->>TestSuites: pytest
    TestSuites-->>WindowsJob: launcher and install.sh tests pass
Loading

File-Level Changes

Change Details Files
Runs the launcher and installer test suites under Git for Windows Bash in the Windows CI job instead of skipping them.
  • Locates Git Bash beside the Git executable rather than relying on PATH resolution.
  • Fails the Windows job when Git Bash is unavailable and reports the selected executable.
  • Removes Windows skips and applies the Git Bash session environment to both suites.
 .github/workflows/tests.yml
tests/conftest.py
tests/test_openreposhape_command.py
tests/test_install_sh.py
Adapts cross-platform test fixtures and assertions to Git Bash's Windows behavior.
  • Converts paths with Git's cygpath and writes shell scripts with LF endings.
  • Uses byte output for shell-sensitive fake responses and validates executability through Bash on Windows.
  • Replaces PATH symlinks with shell wrappers where Windows DLL resolution requires it.
  • Covers newline-containing arguments and Git Bash's copy-versus-native-symlink behavior.
 tests/conftest.py
tests/test_openreposhape_command.py
tests/test_install_sh.py
Documents Git Bash as a supported native Windows environment and synchronizes handbook references.
  • States that the one-line install and command work in Git Bash while PowerShell uses the two-command setup.
  • Clarifies that WSL2 runs Bash entry points inside Linux.
  • Updates the handbook masthead and README section hashes.
 README.md
docs/handbook.html

Possibly linked issues

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

@brettheap brettheap mentioned this pull request Oct 15, 2026
Merged
brettheap and others added 2 commits October 15, 2026 11:49
@brettheap
Merge branch 'main' into l3-564-carry-to-main
25b2aee
Brett Heap @claude
README.md and docs/handbook.html: Git Bash runs the one-line install …
01e8c2c 
…and the openRepoShape command, tested in CI but for a typed `yes`, which the preflight the one-line install ends with cannot take there, so README and the handbook no longer call that flow supported as a whole; the tests anchor two Windows-only paths and drop an inherited `MSYS` (#585)

The review on #596 (rv585, S1): under `curl ... | bash`, install.sh
runs `exec </dev/null` (install.sh:277), and setup-project.py's
`open_terminal()` has no Windows path, so in Git Bash the preflight that
the one-line install ends with cannot take a typed `yes`. Nothing installs
without one, so consent holds; the claim did not.

README.md (line count unchanged, 1449):
- the Windows paragraph says Git Bash runs the command and the one line,
  tested in CI but for a typed `yes`, which its preflight cannot take;
- step 3 says the preflight's offers wait for a typed `yes` at your
  terminal, and that in Git Bash it can take none.

docs/handbook.html:
- the Windows panel says the same, at length;
- the consent rules say that in Git Bash the preflight can take no `yes`,
  so it installs nothing;
- step 3's install paragraph is `data-platform="linux mac wsl"` and is left;
- the seven markers for README.md § Starting a project in a new
  organisation record its new hash.

tests/test_openreposhape_command.py:
- the fetched-setup.sh test asserts that the parent of the directory the
  stub ran in exists, so its "the directory is gone" line cannot pass on
  a path Python cannot open (`/tmp/...` read as a Windows path);
- the `ln -s` test drops a `$MSYS` inherited from the caller, so its
  default case is Git Bash's default, a copy.

tests/conftest.py: `git_bash_session` puts `clangarm64\bin` and
`MSYSTEM=CLANGARM64` on PATH where Git for Windows has `clangarm64` (ARM64),
`mingw64` otherwise.

.github/workflows/tests.yml: the guard step's comment says what probe 1
showed: a bare `bash` runs System32's WSL launcher, because CreateProcess
searches System32 before PATH, and the `bash` PATH names first,
`Git\bin\bash.exe`, puts Git's real `curl` ahead of the suites' fake.

A correction to the first commit's message: the launcher's suite runs
`bash -s` with argv[0] `bash` and `BASH` as the executable; the
installer's suite still passes `BASH` as argv[0], as before, and
install.sh reads neither `$0` nor `BASH_SOURCE`.

Lane: openreposhape-5 (openRepoShape-5)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@brettheap brettheap changed the title tests: the launcher's and install.sh's suites run in the Windows job under Git for Windows' own bash, so the one-line install is tested on Windows, and README and the handbook say Git Bash is supported (#585) tests: the launcher's and install.sh's suites run on Windows under Git for Windows' own bash, so the one-line install is tested there; README and the handbook say Git Bash runs it, but its preflight cannot take a typed yes (#585) Oct 15, 2026
Brett Heap @claude
tests/test_openreposhape_command.py: the fetched-setup.sh test assert…
3095a9c 
…s on one native path, so its parent-directory anchor also pins the line that says the directory is gone (#585)

The two asserts now share `ran_dir`, so reverting `native_path` for the existence check alone no longer passes beside a still-true anchor. This answers the re-review's nit 1.

Lane: openreposhape-5 (openRepoShape-5)
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@brettheap brettheap mentioned this pull request Oct 15, 2026
Merged
Brett Heap and others added 3 commits October 15, 2026 17:16
Brett Heap @claude
Merge remote-tracking branch 'origin/main' into l3-564-carry-to-main
b23b245 
Brings in #597 (654c476, CI on Linux only), with #565 and #555 before it.
Three conflicts:
	.github/workflows/tests.yml: main's file whole. #587's
	  `/bin/bash -n install.sh` and its comment lived in the macOS job #597
	  removed; no bash 3.2 step is added anywhere, as #597 decided, and this
	  pull request no longer touches tests.yml.
	README.md: the macOS sentence keeps #587's `install.sh` in the list and
	  takes #597's wording: "`setup.sh`, `install.sh` and the `openRepoShape`
	  command are written to use no syntax newer than that, though CI runs on
	  Linux only and no run of it checks them against bash 3.2", with "all
	  three entry points" after it. Four lines, as both sides had: README.md
	  stays 1449 lines, its cap with tests/readme-cap.d/564.txt (+22).
	docs/handbook.html: the macOS panel's sentence says what the merged
	  README says. The seven markers that read README.md § Starting a
	  project in a new organisation (masthead, start, partway, ci, legs,
	  doublepin, park) move to a0e0f23c306cebdf627d90225e33c277f05de64b, as
	  the hygiene check printed; the macOS sentence is the only part of that
	  section the merge changed, and no other part of the seven speaks of
	  CI's runners or bash 3.2. The footer is the same on both sides.
test_install_sh.py's pin check still holds: the Linux job installs
git-filter-repo==2.47.0, install.sh's pin. The tests' dated history that
names the macOS job stays, as #597 left it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brett Heap @claude
Merge l3-564-carry-to-main b23b245 (main 654c476, #597's Linux-only C…
f655286 
…I) into fix/585-git-bash-windows: tests.yml is the base's, without #596's guard step in the gone tests-windows job, and the handbook keeps #597's macOS panel beside #596's Git Bash text, its seven markers moved to the merged README (#585)

The base, lane 3's #587 branch, merged main 654c476, which holds #597 ("ci:
run the test suite on Linux only", merged by Brett Heap 2026-10-15T16:54:43Z).
#597 removed the tests-windows and tests-macos jobs, made README's macOS
sentence and the handbook's macOS panel say CI runs on Linux only, and moved
the seven handbook markers for README.md section "Starting a project in a new
organisation". Two files conflicted.

.github/workflows/tests.yml: the base's file, byte for byte (blob b2de8af).
Dropped from this branch:
- the step "Git Bash is the bash the launcher and installer suites run",
  which sat in tests-windows;
- the tests-macos comment's clause that the windows job runs the command
  only under Git Bash.
Both jobs are gone, so both hunks went with them. At this commit alone no CI
job runs the two suites under Git Bash, so README's "tested in CI" is not yet
true here. The next commit adds the small tests-git-bash job, on Brett Heap's
word at 2026-10-15T18:20:35Z: "Option 1: keep a small Git Bash job for #596".

docs/handbook.html: the base's text, with #597's macOS panel, and this
branch's Git Bash text (the masthead, the Windows panel, the consent rules),
which merged as text. The seven conflicts were the seven markers for README.md
section "Starting a project in a new organisation": this branch's 26629e7a
against the base's a0e0f23c. Each now records a88ac2d0315c9c8ed6e962ab6ae34b856346ecc9,
the merged section's hash, computed with tests/test_repo_hygiene.py's own
readme_segments and readme_fingerprint.

README.md merged cleanly as text: #597's macOS sentence and this branch's
Windows paragraph and step-3 clause are in different paragraphs. It is 1449
lines, the cap (1422 + 5 for 550.txt + 22 for 564.txt).

Every other file is the base's. Against the base, this merge differs only in
this branch's five files: README.md, docs/handbook.html, tests/conftest.py,
tests/test_install_sh.py and tests/test_openreposhape_command.py.
tests/test_repo_hygiene.py and tests/test_readme_sections.py: 141 passed on
the merged tree.

Lane: openreposhape-5 (openRepoShape-5)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brett Heap @claude
.github/workflows/tests.yml, README.md and docs/handbook.html: a smal…
5f001de 
…l `tests-git-bash` job runs the launcher's and the installer's suites on windows-latest under Git Bash, on every trigger, as the one exception to #597 on Brett Heap's word, so README's Git Bash sentence is tested in CI again and the macOS sentence no longer says CI runs on Linux only (#585)

#597 (main 654c476) dropped the Windows and macOS jobs for the whole
estate, and the merge before this commit took that workflow. That left
README's "Git Bash runs that command and step 3's one line, tested in CI but
for a typed `yes`" with nothing behind it. Brett Heap, 2026-10-15T18:20:35Z:
"Option 1: keep a small Git Bash job for #596". The option he picked: a small
Windows job for just these two suites, which finishes inside the Linux job's
time and keeps README's claim true, as an exception to #597's decision.

The workflow:
- The header keeps #597's text and adds one sentence naming the exception,
  with his word and its time.
- `tests-git-bash`: windows-latest, `timeout-minutes: 15`, no `if:`, so it
  runs on a push to main, on pull requests and on a manual run. A squash
  lands a tree no pull-request run tested (#122), and these two suites are
  the only run of the one-line install on Windows.
- Its steps: checkout and setup-python at the ubuntu job's two commits
  (`fetch-depth: 0`, because the launcher's suite clones this checkout
  itself in test_a_ref_the_doctor_would_check_out_is_validated); pytest
  8.3.4; the git identity, appended to GITHUB_ENV in PowerShell as the old
  Windows job did; the guard step "Git Bash is the bash the launcher and
  installer suites run", which fails the job when conftest finds no Git
  Bash; then `python -m pytest -q -rA tests/test_openreposhape_command.py
  tests/test_install_sh.py`, with the old job's `--basetemp` under
  `runner.temp` for MAX_PATH.
- Its env is the old Windows job's: PYTHONUTF8=1 (the suites decode bash's
  output with `text=True`, and the launcher's `--help` prints em dashes),
  core.autocrlf=false and core.longpaths=true. Every Windows run of these
  two suites, #585's four probes included, had all three.
- Left out: git-filter-repo, because these suites never reach a real one
  (the install suite fakes it and pipx; the launcher's machine report gets
  a fake on the PATH it builds; on Linux the two suites pass with no
  git-filter-repo on PATH); and actionlint, which the ubuntu job runs on
  this file. tests/test_install_sh.py's pin check still finds the ubuntu
  job's git-filter-repo pin.

The docs. README's macOS sentence and the handbook's macOS panel said "CI
runs on Linux only and no run of it checks them against bash 3.2". They now
say "no CI run, on Linux or in Git Bash on Windows, checks them against bash
3.2", which is true with this job and keeps README at 1449 lines, its cap.
README's Windows paragraph and the handbook's Windows panel already say CI
tests Git Bash, and are true again. The seven handbook markers for README.md
section "Starting a project in a new organisation" record its new hash,
34723d9ae3d5e64cde648576855ce706589ffc0d.

actionlint 1.7.12 on tests.yml and the two template workflows: exit 0.
Linux, before this commit: tests/test_repo_hygiene.py,
tests/test_readme_sections.py, tests/test_cli_reference.py and
tests/test_setup_by_hand_commands.py, 168 passed; the two suites, 113
passed, and 113 passed again with no git-filter-repo on PATH.

Lane: openreposhape-5 (openRepoShape-5)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@brettheap brettheap changed the title tests: the launcher's and install.sh's suites run on Windows under Git for Windows' own bash, so the one-line install is tested there; README and the handbook say Git Bash runs it, but its preflight cannot take a typed yes (#585) tests: a tests-git-bash job runs the launcher's and install.sh's suites in Git for Windows' own bash, so README and the handbook say Git Bash runs the one-line install, tested in CI but for a typed yes, which it cannot take there (#585) Oct 15, 2026
brettheap and others added 3 commits October 15, 2026 14:56
@brettheap
Merge branch 'main' into l3-564-carry-to-main
d5011b1
Brett Heap @claude
.github/workflows/tests.yml: the header says the FULL suite runs on L…
fe58d66 
…inux only, and the `tests-git-bash` comment gives its measured minute and a half instead of three minutes (#585)

Review rv585c's N1: read alone, the header's first sentence said no suite runs off Linux now that `tests-git-bash` exists, so it says the FULL suite does, and the exception sentence after it is unchanged. N3: the job's comment said "about three minutes", the probes' figure, and the PR's own first run measured 86 s, 50 s of it pytest, so it says a minute and a half; comments only.

Lane: openreposhape-5 (openRepoShape-5)
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Brett Heap @claude
Merge remote-tracking branch 'origin/main' into l3-564-carry-to-main
f9b07c9 
Brings in main bcfa364: #588 (709eec1, POSIX-quoted paste lines and
README's Windows sentence) and #569 (bcfa364, setup-project.py's paste
lines). One conflict:
	docs/handbook.html: the seven markers that read README.md § Starting a
	  project in a new organisation (masthead, start, partway, ci, legs,
	  doublepin, park) conflicted, this branch's a0e0f23c against #588's
	  95f06438. Both moved to the merged section's blob,
	  d77a1e59fe4951aa2a6f96808725d0506d4ce357, as the hygiene check printed.
	  Both sides' prose merged on its own: #588's POSIX-quoting sentence in
	  the Windows panel beside #587's install step, NOTE and macOS sentence.
	  Re-read: nothing in the seven sections is made false by the other side.
README.md and docs/cli.md merged cleanly with both sides' hunks, and
`render-cli-reference.py --check` passes. README.md is 1449 lines (cap
1449) and AGENTS.md 492 (cap 492, raised by #566 on main).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brett Heap @claude
Merge main 77bb5f0 (22eacee, #587's squash, and #615's bootstrap.py a…
4c3b72a 
…fter it) into fix/585-git-bash-windows: the four files that conflict take this branch's copy, because main's copy of each is byte for byte #587's final head 3d8fa05, which the merge before this one already holds (#585)

#587 squash-landed on main as 22eacee, whose tree is #587's final head
3d8fa05 merged onto main 2b6dbb7. The previous commit merged 3d8fa05, so
this branch already holds #587's every change; main merges the commits
3d8fa05 did not have: 2b6dbb7 (#584, adopt-project.py's symlink finding) and
77bb5f0 (#615, bootstrap.py and its templates, landed after 22eacee).

The squash is not an ancestor of 3d8fa05, so the merge base is 62ef256 and
four files conflict although both sides hold the same #587 text:
README.md, docs/handbook.html, tests/test_install_sh.py (add/add) and
tests/test_openreposhape_command.py. For each, `git show 3d8fa05:<file>` and
`git show origin/main:<file>` are the same blob, and 77bb5f0 does not touch
it:
- README.md                            d164131
- docs/handbook.html                   59ec34d
- tests/test_install_sh.py             34c7de5
- tests/test_openreposhape_command.py  5e49547
So main's copy is 3d8fa05's copy, and ours is 3d8fa05's plus this branch's
change: each takes ours (`git checkout --ours`). No file was merged by hand.

Every other file merged as text. Against main this merge differs only in this
branch's six files: .github/workflows/tests.yml, README.md,
docs/handbook.html, tests/conftest.py, tests/test_install_sh.py and
tests/test_openreposhape_command.py (430+, 141-), and
`git merge-tree --write-tree HEAD origin/main` gives this commit's own tree.

Lane: openreposhape-5 (openRepoShape-5)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@brettheap brettheap mentioned this pull request Oct 15, 2026
Merged
Brett Heap @claude
Merge main 396c0ff (#598's install.sh, 3fb21d9, and four more) into f…
52524fe 
…ix/585-git-bash-windows: README's step 3 keeps #598's pipx-or-uv paragraph and this branch's "in Git Bash it can take none" inside its 1449-line cap, the handbook's consent rule keeps both, and the seven markers move to the merged README (#585)

Main moved from 77bb5f0 to 396c0ff: 55faad2 (#591), fbbbc8d (#572),
7fdec0a (#624), 3fb21d9 (#598, lane 3's #595) and 396c0ff (#570). Only
#598 touches this branch's files: README step 3's install.sh paragraph, the
handbook's masthead and `start`, install.sh and tests/test_install_sh.py, and
it adds tests/test_install_sh_filter_repo.py. Two files conflicted.

README.md, one region: step 3's install.sh paragraph. #598 rewrote it for
uv and the closing readinesses; this branch had added "in Git Bash it can
take none" after "each behind a typed `yes` at your terminal". Side by side
that is nine lines where both have eight, and README is at its cap (1422 + 5
for 550.txt + 22 for 564.txt = 1449). The cap is not raised. Two rewordings
fit it, and no fact is dropped:
- "`install.sh` is attached to every release and installs the newest, with
  no `gh` and no login." became "`install.sh`, attached to every release,
  installs the newest with no `gh` and no login."
- #598's "`install.sh` never runs `sudo`;" became "It never runs `sudo`
  itself;". "It" is install.sh, the subject of the sentence before it, and
  "itself" is #564's own word for the contrast with the preflight.
#598's "It installs `git-filter-repo` with `pipx`, or `uv`, where it can, or
prints the command, runs `openRepoShape --preflight`, and says last if the
machine is ready to adopt or only to scaffold" is word for word, and so is
this branch's "; in Git Bash it can take none". The eight lines rewrap at
80 characters at most, as 78 README lines already are.

The Git Bash clause is still true after #598. Under `curl ... | bash`,
install.sh's `[ -t 0 ] || exec </dev/null` (install.sh:342, which #598 does
not touch) leaves the preflight no terminal on stdin. Under Git Bash
setup-project.py runs on native Windows Python, where `open_terminal()`
returns None (`os.name == "nt"`), so `can_ask()` is False, and `offer()`
takes no `yes`. #598 changes what install.sh does before and after the
preflight, not how the preflight reads an answer.

docs/handbook.html, eight regions:
- The consent rules' install.sh item keeps #598's text, "installs
  `git-filter-repo` with `pipx` or `uv` where one is there, and itself never
  runs `sudo` or installs either of them", and then this branch's clause, word
  for word: "; in Git Bash it can take no `yes`, so it installs nothing."
- The seven markers for README.md section "Starting a project in a new
  organisation" (this branch's 278a1947 against #598's d1666fa6) each record
  badbb6b273215042ba0e8ae167fd760dc25430ee, the merged section's hash from
  tests/test_repo_hygiene.py's own readme_segments and readme_fingerprint.
  All 23 markers match the merged README.
The masthead merged as text: this branch's "macOS, Linux, WSL2, Git Bash"
heading and PowerShell line, beside #598's "where `pipx` or `uv` can install
it ... and whether the machine is ready to adopt or only to scaffold".
The `start` step-3 paragraph is #598's; it is `data-platform="linux mac
wsl"`, as before.

tests/test_install_sh.py merged as text. #598's hunks (`no_pipx` and
`no_pipx_but_apt`'s printed commands, the docstring, and the line before the
printed command, which now starts "there is neither pipx nor uv") sit beside
this branch's `bash_path` in `present_on_path` and in the preflight line of
the same test. tests/test_install_sh_filter_repo.py comes in unchanged. It
builds on `Net`, whose `fake` this branch writes as LF bytes, and it is not
added to the tests-git-bash job.

Against main this merge differs only in this branch's six files:
.github/workflows/tests.yml, README.md, docs/handbook.html,
tests/conftest.py, tests/test_install_sh.py and
tests/test_openreposhape_command.py (436+, 147-). `git merge-tree
--write-tree HEAD origin/main` gives this commit's own tree.
tests/test_repo_hygiene.py, tests/test_readme_sections.py and
tests/test_readme_windows_quoting_sentence.py: 144 passed on the merged tree.

Lane: openreposhape-5 (openRepoShape-5)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sonarqubecloud

sonarqubecloud Bot commented Oct 15, 2026

Copy link
Copy Markdown

Quality Gate Passed 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

@brettheap brettheap mentioned this pull request Oct 15, 2026
Merged
@brettheap
brettheap marked this pull request as ready for review October 15, 2026 23:35
@sourcery-ai

sourcery-ai Bot commented Oct 15, 2026

Copy link
Copy Markdown

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

@brettheap
brettheap merged commit bf7b19b into main Oct 15, 2026
4 checks passed
@brettheap
brettheap deleted the fix/585-git-bash-windows branch October 15, 2026 23:36
brettheap pushed a commit that referenced this pull request Oct 15, 2026
Brett Heap @claude
Merge origin/main bf7b19b into fix/606-readme-followups: #596's Git B…
a6d4f5f 
…ash sentences and #606's three sentences both stay in README and the handbook, so the page's seven § Starting markers read the merged section's hash (#606)

Merges main bf7b19b (#583, #625 and #596 since the last merge, 396c0ff).
Only #596 touches README.md and docs/handbook.html; #583 and #625 change code
and tests, taken as main has them.

README.md merged without a conflict. #596 rewords three places in README
§ Starting a project in a new organisation (the Windows and Git Bash paragraphs
of its install section) and #606 adds a sentence to the part-way box in the
same section, so that section's hash is neither branch's (#606: 51702a2b, main:
badbb6b2) but a third one, fe0d932b.

docs/handbook.html conflicted in seven hunks, all of them the one marker line
of the seven page parts that read that section (masthead, start, partway, ci,
legs, doublepin, park). The text around the markers merged without a conflict,
so both sides' sentences are kept: #596's Git Bash words and #606's partway and
adopt mirror sentences. Each of the seven markers now names
fe0d932b031e4a08fc885f93d6cd978df0d5a25c, the merged README section's
fingerprint, computed with the hygiene test's own readme_segments and
readme_fingerprint. The § Adopting marker, ca4b6731, stays: #596 does not touch
that section.

README is 1456 lines against a cap of 1422 + 5 (550.txt) + 22 (564.txt) + 7
(606.txt) = 1456. #596 added no cap file (it rewords within the cap), so the
cap is unchanged by the merge.

Lane: openreposhape-2 (openRepoShape-2)
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This was referenced Oct 15, 2026
Merged
Open
Open
brettheap pushed a commit that referenced this pull request Oct 16, 2026
Brett Heap @claude
Merge origin/main f6376d7 into fix/610-pinned-text, so the PR's pinne…
6e3dd1d 
…d-copy text is tested and pushed on the current main (#610)

Merges f6376d7 (the squash of #614) and the main commits between this
branch's base 396c0ff and it: #625 (family.py `bump --to`), #583
(adopt-project.py branch names), #596 (README, handbook and the
tests-git-bash job) and #614 (adopt-project.py `git rm` bytes). No file
this PR changes is among the files main changed since 40a85e1, and
`git merge-tree --write-tree` was clean (tree 30b0fbf), so no hunk was
resolved by hand. The pinned shape copies still move as one re-pin.

Lane: openreposhape-2 (openRepoShape-2)
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@brettheap brettheap mentioned this pull request Oct 16, 2026
Merged
brettheap pushed a commit that referenced this pull request Oct 16, 2026
Brett Heap @claude
Merge origin/main (4cf5fb0, with #596's tests-git-bash job) into l3-5…
cfbe59d 
…63-pypi-package

One conflict, .github/workflows/tests.yml. Main's file is kept whole:
#597's Linux-only `tests` job, #593's `concurrency:` group, and #596's
header exception and `tests-git-bash` job (on Brett Heap's word
"Option 1: keep a small Git Bash job for #596"). This branch adds to it
only its own two parts, unchanged: the header paragraph on the `package`
job, after main's, and the `package` job at the end, byte for byte as at
995e138. The jobs are `tests`, `tests-git-bash` and `package`.

tests/test_install_sh.py and tests/test_openreposhape_command.py merged
cleanly: each one's diff from main is exactly this branch's lines (the
symlink refusal cases), and its diff from this branch exactly main's.
Lane 5's `bash_path` hunks for those cases follow in their own commit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
brettheap pushed a commit that referenced this pull request Oct 16, 2026
Brett Heap @claude
tests/test_install_sh.py, tests/test_openreposhape_command.py: the tw…
4410da0 
…o symlink refusal cases spell paths as Git Bash does, so they pass in tests-git-bash (#563, #585)

Lane openRepoShape-5's work, applied as lane 5 wrote it: #596 (#585)
landed first, so #590, landing second, carries these hunks. In both
cases the refusal is matched against `bash_path(link)`, the launcher's
case hands `OPENREPOSHAPE_BIN_DIR` over as `bash_path(bin_dir)`, and a
link read back has Windows' `\\?\` prefix stripped before it is compared.
`bash_path` is #596's, in tests/conftest.py, and returns the path as it
is off Windows.

Lane 5's evidence: on Windows (probe run 38769166462, the merge of
01e8c2c with this branch) the four cases failed without the hunks and
both suites gave 117 passed with them; on Linux, 117 passed. Here, on
Linux: the two suites give 117 passed, with and without Path.write_text
writing CRLF.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@brettheap brettheap mentioned this pull request Oct 16, 2026
Merged
brettheap pushed a commit that referenced this pull request Oct 16, 2026
Brett Heap @claude
Merge origin/main (4cf5fb0) into l3-563-docs
2a7865e 
main gained #583 (#520), #596 (#585), #614 (#527), #619 (#530), #594
(#526), #617 (#525) and #618 (#418). Three files conflicted:

- .github/workflows/tests.yml: main's file (with #596's tests-git-bash
  job) plus this branch's three additions, byte-identical to theirs: the
  header paragraph on the `package` job (#590), after main's Git Bash
  paragraph; #599's actionlint line for release.yml; and #590's `package`
  job, now after tests-git-bash. actionlint 1.7.12 finds nothing in it.
- README.md, the native Windows block's closing paragraph: #596 says the
  two-liner IS the Windows way in from PowerShell, with no twin of the
  `openRepoShape` command, and that Git Bash runs that command and the one
  line, tested in CI but for a typed `yes`; this branch says the two-liner
  is the way in that installs nothing and pipx's `openRepoShape` runs the
  same flow. The merge keeps both facts in main's seven lines: the two-liner
  installs nothing, pipx's command runs the same flow, and Git Bash runs
  step 3's bash command and its one line, tested in CI but for a typed `yes`.
- docs/handbook.html: the same two sentences in the masthead's second-way
  paragraph and the Windows panel, each combined the same way, and the
  seven `Starting a project in a new organisation` markers, which now read
  the merged README (62737be2). No other section's marker moves.

README.md is 1477 lines, its cap (1449 on main, +28 for #563).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
brettheap pushed a commit that referenced this pull request Oct 16, 2026
Brett Heap @claude
docs/release-notes/v1.1.0.md: refreshed at main 4cf5fb0 (49 pull requ…
b006f16 
…ests, 57 of 82 milestone issues closed), with #583, #596, #614, #619, #594, #617 and #618 in their areas, #596's Git Bash facts for its placeholders, release.yml's step 1 whole, and every pull request cited beside its issue (RV630 SHOULD 3, 5, 6, nits 7, 8)

- SHOULD 5: step 1 matches release.yml's header: "always on a
  `release/v<X.Y>` branch, which no push run tests", "A `release/v<X.Y>`
  branch serves while it is still at that commit", and that a tag's
  dispatch running at the tag's commit is GitHub's documented behaviour,
  not yet seen here.
- SHOULD 6: #598 beside #595, #592 beside #593, #460 on #557's line, and
  #589's line says "where that clone is still on the machine and is no
  partial clone" again. The counts and the open-issue list are re-derived
  from `git log --first-parent bfed143..origin/main` (49) and the
  milestone (25 open, 57 closed: #342, #392, #393, #421, #423, #426,
  #432, #433, #434, #443, #444, #454, #455 and #629 joined it). New lines
  under adopt-project.py for #583 (#520, #420), #619 (#530), #618 (#418),
  #614 (#527), #594 (#526) and #617 (#525); #596 (#585) under the one-line
  install, CI, native Windows, the docs and the known limits, where the
  two placeholders for it were.
- SHOULD 3: the known limit about "the installed doctor's temporary
  clone" is gone; the README, the handbook and AGENTS.md no longer say it.
- SHOULD 1: the filter-repo line says install.sh's order, apt and dnf
  included.
- nit 7: the release process's preconditions are said as the process
  this release follows; the workflow checks the environments, and nothing
  checks the rehearsal.
- nit 8: the known limits are wrapped.
- "the first on native Windows, where the one line cannot run" says
  PowerShell cannot run it, since Git Bash does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
brettheap pushed a commit that referenced this pull request Oct 16, 2026
Brett Heap @claude
Merge remote-tracking branch 'origin/l3-563-pypi-package' into l3-563…
750366b 
…-release-workflow

Brings in #590 at 70955e4: its merge of main (#596's `tests-git-bash`
job, #593's concurrency group, #597's Linux-only `tests` job), lane 5's
`bash_path` hunks and a header-comment fix. No conflict: git merged
tests.yml by itself. The result is #590's file whole (jobs `tests`,
`tests-git-bash`, `package`, and its header wording) plus only #599's
own change: `.github/workflows/release.yml` in the actionlint step, with
its comment and step name. Every other path is #590's, plus #599's own
files and its pyproject.toml comment paragraph.

The release gate stays ("tests",): `tests-git-bash` is not a release
gate.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@brettheap brettheap mentioned this pull request Oct 16, 2026
Merged
brettheap pushed a commit that referenced this pull request Oct 16, 2026
Brett Heap @claude
Merge origin/l3-563-release-workflow (750366b, #599 with #590's 70955e4…
ca5c49f 
…) into l3-563-docs

#599 now merges #590's 70955e4, which carries main 4cf5fb0 (#596's
tests-git-bash job), lane 5's `bash_path` spellings in the two symlink
refusal tests, and the reworded header paragraph on the `package` job. CI's
tests-git-bash job failed #630's b006f16 on those four symlink cases,
because this branch still held #590's older test files.

Two files conflicted, as RV630's simulation predicted:

- .github/workflows/tests.yml, the `package` job's header paragraph only:
  #590's wording. The file is now 750366b's, which is 70955e4's plus
  #599's actionlint lines for release.yml.
- docs/handbook.html, the seven `Starting a project in a new organisation`
  markers, from the criss-cross merge base: this branch's side. README.md
  merged cleanly to b006f16's, and the handbook is b006f16's, byte for
  byte.

tests/test_install_sh.py, tests/test_openreposhape_command.py and
tests/test_openreposhape_package.py merged cleanly to 70955e4's. The
merged tree differs from 750366b only in this pull request's own ten
files.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@brettheap brettheap mentioned this pull request Oct 16, 2026
Closed
5 tasks
brettheap added a commit that referenced this pull request Oct 16, 2026
@brettheap @claude
family.py and validate-family.py: where an earlier act left the branc…
95780dd 
…h, the `switch -c` remedy says to give it another name, or go back only if it holds work not merged yet, and the docs say `family/add-<Project>` (#607) (#637)

### Fix round 1 (rv607)

Review rv607 of 6212c31 said CHANGES NEEDED: 0 blockers, 2 should, 7 nits. This round is one new commit, 66b1043, on top of 6212c31. No amend, and main is not merged in. Each point:

- **S1, the sentence.** It sent a person back to the old branch first. That is right only where the branch holds work not merged yet. `BRANCH_LEFT` now puts another name first and going back second (the text is under "L2-46" below). It is word for word the same in `scripts/family.py`, in the pinned `validate-family.py` and in the pinned test constant, and the comments that described the old order are rewritten. Two new tests type the printed line in the states the review probed: `main` has moved since the earlier act, and a commit was made on a detached HEAD.
- **S2, a guard for every `_switch_line` remedy.** A new test reads the validator's source with `ast` and fails any remedy that names `_switch_line` whose prose does not end with `BRANCH_LEFT`. On a merge of this head with #634 it fails at `_lockstep`, which is the point: whichever of #637 and #634 lands second adds the sentence there. #634's lines are not on this branch and are not touched.
- **N1.** Under "Left out".
- **N2.** The commit body of 6212c31 said neither tool can print the one line that works by asking first. That holds for the validator only. `family.py` could ask; it says the validator's words so the two tools keep one rule. Decision 1 says so, and the new commit's body corrects the old one.
- **N3.** The merge table is refreshed: current origin/main, #620, #622, #626, #630 to #636, #638, #639 (lane 5's #611) and #634 (S2).
- **N4.** Decision 1 no longer says the typed line works "in every shell". It says what a person types is "the printed line with one word changed (the branch name, or `-c` taken out)", so it keeps the printed quoting, and that the tests type both changes as printed.
- **N5.** Decision 3 now says the case of the branch name "does not matter to `add`", and adds the note about case-insensitive disks.
- **N6.** The `init` NEXT STEPS test read the lines with a regex whose `--family-root \S+` breaks on a root with a space in it (`C:\Users\Jane Doe`, or any `tmp_path` with a space). It now reads the words with `host_words`, as the NEXT STEPS test beside it does. Run with a space in the base temp directory, the old test fails with `AttributeError: 'NoneType' object has no attribute 'group'` and the new one passes.
- **N7.** "Three existing tests take the new text" was wrong. It is two test functions plus `GITLINK_REMEDY`, a constant four cases share. Fixed under "Tests". The one new test that passes on BASE is disclosed there too.

### Fix round 2 (rv607b)

The re-verify rv607b of 66b1043 said APPROVE WITH NITS: 0 blockers, 0 should, 5 nits. This round is one new commit, a277695, on top of 66b1043. No amend, and main is not merged in. It changes comments and docstrings only, so no behaviour moves and no mutation row changes.

- **Nit 1.** Two comments called another name "right in every state". It is not: where the old branch holds work not merged yet, another name leaves that work behind. The comment above `BRANCH_LEFT` in `scripts/family.py` and the one in the pinned `validate-family.py` now say a new branch starts where the holder stands now, "which works in every state". The three `BRANCH_LEFT` texts are unchanged and still equal.
- **Nit 3.** The guard's docstring said it finds each `_switch_line` call "however it is passed on". A switch line moved into a variable would defeat that. It now says "wherever the call stands inside the string expression that is passed on".
- **Nit 4.** The N4 line above now quotes decision 1 as written.
- **Nit 5, the docstring half.** The docstring of `test_another_name_works_where_main_has_moved_since` said going back to the old branch conflicts, but the test does not assert that. It now says the test shows the other name works, and that the conflict on the old branch is shown by rv607's probe and decision 2's table. No assertion is added.
- **Nit 2, left as written.** The guard's control counts stay: each case fails loudly with a clear message.

Checks on a277695: the diff to 66b1043 adds ten lines and removes seven, in three files, all comments and docstrings, and the `ast` of each file is equal once docstrings are blanked. The four files `test_family_switch_branch_exists.py`, `test_validate_family_branch_step.py`, `test_validate_family_unnamed_mounts.py` and `test_family_tracking_branch.py` give `96 passed in 51.34s`, and `test_repo_hygiene.py` gives `65 passed in 1.39s`.

### L2-46, the fix

`family.py add`, `bump` and `remove` refuse the holder's tracking branch with `git -C <holder> switch -c family/<act>-<member>` (#487). The holder's `validate-family.py` names the same line before each `add` and `remove` it prints (#539, landed as 54041cc). If an earlier act left that branch, the line fails with `fatal: a branch named 'family/add-atlas' already exists` (exit 128), and neither tool said what to do next.

Both tools now add one sentence, in the same words (`BRANCH_LEFT` in each file):

> If `git switch -c` says that branch already exists, an earlier act left it: give the branch another name, which starts it where the holder stands, or, only if that branch holds work not merged yet, the same command with `switch` in place of `switch -c` goes back to it and keeps every commit on it.

- `scripts/family.py`: the sentence comes on its own line, right under the `switch -c` line, in the `family-on-tracking-branch` and `family-holder-detached` refusals (`_checked_branch`), and in the dry run's `branch` lines (`_branch_said`).
- `templates/family-root/scripts/validate-family.py`: the sentence ends the remedy text of `member-gitlink-absent`, `member-duplicate-id` and `member-gitlink-unnamed`, the three remedies that print `_switch_line`. The command lines under them are unchanged.

### L2-45, rides along

AGENTS.md, the holder's README, its AGENTS-shape.md and `init`'s NEXT STEPS spelled the branch `family/add-<project>`, right beside `--member <org>/<Project>`. All four now say `family/add-<Project>`, the one placeholder the validator already uses for both (`PROJECT_PLACEHOLDER`, #539).

**1. What the remedy prints when the branch exists: one sentence that names the way out, not a second command line.**

- *One line that works in both states* (`git switch X 2>/dev/null || git switch -c X`): rejected. On Windows, `family.py` quotes its lines for PowerShell (`shell_line` uses `os.name`; README.md:155-158 says so). Windows PowerShell 5.1 has no `||`; `&&` and `||` arrived in PowerShell 7, and `family.py`'s own `_print_next_steps` docstring says 5.1 rejects `&&`. PowerShell also has no `/dev/null`. And `2>/dev/null` would hide the real reason a `switch` fails, such as a changed file it would overwrite.
- *The tool checks and prints the one line that works*: rejected for the validator. Its report is read in CI: the holder's `validate.yml` runs `python3 scripts/validate-family.py` (and `--no-members`) in a runner's checkout, which holds none of the person's branches. `family.py` could check, but then the two tools would follow two rules, and one rule in the same words was the aim. So `family.py` says the validator's words; it is not that it cannot ask.
- *Two printed lines, one per state*: rejected. In the validator, each indented line is a step to run in order, and going back to the branch replaces step one; it is not another step. In `family.py`, a new `git switch` line would also be quoted for PowerShell on Windows. README.md:155-158 lists exactly which `family.py` lines are quoted that way (`NEXT`, `switch -c`, `add`, `git rm -r --cached`). That sentence would become false, and fixing it would mean editing README § "Starting a project in a new organisation". Seven handbook parts record that section's hash (`grep -c` gives 7).
- *Chosen*: a sentence that names both ways out. It prints no new command, so nothing new needs quoting, and the text is the same in both tools. What a person types is the printed line with one word changed (the branch name, or `-c` taken out), so it keeps the printed quoting. The tests type both changes as printed (tests below); none of them runs a shell, and Windows and macOS are not checked (see "Left out").

**2. Another name first, going back second (S1).** The reviewer's probes, and mine, in real local holders (a holder `Orbit`, members `Atlas` and `Beacon`, local bare remotes, the `gh` stub first on PATH):

| State of the old branch `family/add-atlas` | `git switch family/add-atlas` (going back) | `git switch -c family/add-atlas-2` (another name) |
|---|---|---|
| No commit on it, `main` has not moved (rv607) | works | works |
| Holds a commit of its own, not merged yet (mine: `probe-atlas.sh`, `probe-b.sh`) | works; `add` then commits on top of it, and the earlier commit is the parent | works, but the earlier commit stays only on the old branch (`git branch --contains` names `family/add-atlas` alone) |
| `main` has moved: a later member (`Beacon`) was squash-merged (mine: `probe-d.sh`; test `test_another_name_works_where_main_has_moved_since`) | `add` exits 0, but `git merge-tree --write-tree main family/add-atlas` exits 1 (`CONFLICT (add/add)` in `.gitmodules`, `CONFLICT (content)` in `family.yaml`), and an untracked `members/Beacon` is left (`warning: unable to rmdir 'members/Beacon'`) | `add` exits 0, `git merge-tree --write-tree main family/add-atlas-2` exits 0, and the validator says `2 member(s)` |
| Merged, then the member removed and that merged too; the old branch is still local (rv607's probe, and mine: `probe-c.sh`) | `add` says `member-already-present`, whose remedy points at `bump` and `remove`: a dead end | `add` exits 0, once the object store `remove` leaves behind is deleted, as its NOTE says (either choice needs that) |
| Detached HEAD with a commit made on it (mine: `probe-detached.sh`; test `test_another_name_keeps_a_commit_made_on_a_detached_head`) | `Warning: you are leaving 1 commit behind, not connected to any of your branches`, and `git branch --contains` names no branch | the commit stays: `git branch --contains` names the new branch |

So going back is right only where the branch holds work not merged yet, and another name is right in every state but that one. The sentence says so, in that order.

**3. The person's earlier work on that branch is never discarded.** `git switch <branch>` keeps the branch's commits. It refuses to switch when that would overwrite a changed file. The act then commits on top of what the branch holds; the tests check that the earlier commit is the parent of the act's commit. "Give the branch another name" leaves the old branch alone. No printed line names `switch -C` (which resets a branch), `branch -D`, `reset` or `--discard-changes`; a test checks that too.

**4. The placeholder: `<Project>` everywhere.**

- The validator already said `family/add-<Project>` beside `--member <org>/<Project>` (#539's fix round, pinned by `tests/test_validate_family_unnamed_mounts.py`). It is the only spelling that is one placeholder for both values.
- The other option, a sentence saying the branch word is the name in lowercase, does not fit: AGENTS.md is at its cap, 492 of 492 lines (`tests/test_repo_hygiene.py:633`). This change keeps it at 492.
- The case of the branch name does not matter to `add`. `_checked_branch` takes any branch but the tracking one, so `family/add-IRQS`, the doc line filled in as written, is a branch `add` commits on (test). Where the tools know the name, they still print it lowercased (`_suggested_branch`). On a case-insensitive disk (macOS, Windows) `family/add-Atlas` and `family/add-atlas` can be one loose ref there. That is untested: CI is Linux only.

**5. Pinned copies.** This changes two pinned holder files: `templates/family-root/scripts/validate-family.py` and `templates/family-root/AGENTS-shape.md` (`scripts/shape_materialize.py` lists the pinned set). Each holder takes them as two `upstream-changed` rows on its next `update-shape.py` run. The holder's README is rendered once and is not pinned. No test pins those files' bytes; the tests that compare them read the template at run time. Fix round 1 changes only `validate-family.py` of the two.

New file `tests/test_family_switch_branch_exists.py`, 25 tests (21 before the fix round). Four are new in the fix round:

- `test_another_name_works_where_main_has_moved_since` (S1, state (d)): `family/add-irqs` is left at the `main` of its day; a later member (`IRXS`, scaffolded in the test) is added on a branch and squash-merged onto `main`, so `main` has one new commit; the refusal's `switch -c`, typed as printed, fails with `already exists` (exit 128); the same line with another name works; `add` exits 0, `git merge-tree --write-tree main <branch>` exits 0, and the validator passes.
- `test_another_name_keeps_a_commit_made_on_a_detached_head` (S1): the refusal is `family-holder-detached`; after the printed line with another name, `git branch --contains <the commit>` names the new branch and no other.
- `test_every_remedy_that_names_a_switch_line_ends_with_the_sentence` (S2, the guard) and `test_the_guard_sees_a_remedy_left_without_the_sentence` (its control: the source with the sentence taken out of any one remedy fails it, and so does a fourth remedy built by a helper as `_lockstep` builds its, until the sentence ends it).

The other 21:

- `test_the_refusal_typed_as_printed_puts_the_act_on_its_branch` [add, bump, remove] x [no-branch, branch-left]: the refusal, then its line typed as printed. With no branch, the `switch -c` makes one. With a branch an earlier act left, holding a commit of its own, the `switch -c` fails with `fatal: a branch named '<branch>' already exists` (exit 128) and changes nothing, and the same command with `switch` in place of `switch -c` goes back to that branch. The act then commits on top of the earlier commit, and NEXT pushes that branch.
- `test_a_dry_run_on_the_tracking_branch_says_it_too` [add, bump, remove].
- `test_a_missing_gitlinks_remedy_typed_as_printed`, `test_a_duplicate_ids_remedy_typed_as_printed` (with the `remove` run as printed) and `test_an_unnamed_gitlinks_remedy_typed_as_printed`, each in both states.
- `test_the_two_tools_say_the_same_words`.
- `test_each_doc_spells_the_branch_as_its_member` [AGENTS.md, AGENTS-shape.md, holder README], `test_init_next_steps_spell_the_branch_as_its_member` (read with `host_words` now, N6), and `test_the_branch_filled_in_as_written_is_one_add_commits_on`.

Two existing test functions take the new text: `test_init_next_steps_make_the_branch_before_the_add` (`<Project>`) and `test_a_missing_gitlink_remedy_makes_the_branch_and_names_the_holder` (the remedy line). `GITLINK_REMEDY` in `test_validate_family_unnamed_mounts.py`, a constant four cases share (`test_a_member_mounted_by_hand_is_two_findings` x 3 and `test_a_removed_row_is_named_by_its_gitlink_and_its_section`), ends with the sentence. The sentence is pinned once, as text, in `tests/test_validate_family_branch_step.py`.

Before and after, with the four changed test files copied in (`run9.sh`, the `gh` stub first on PATH):

- On BASE 396c0ff: `30 failed, 66 passed` in the four files. 24 of the 25 new-module tests fail. The one that passes, `test_the_branch_filled_in_as_written_is_one_add_commits_on`, is the evidence for decision 4: it shows behaviour this PR keeps.
- On 6212c31: `23 failed, 56 passed` in the three files that pin the sentence. Both new S1 tests fail there, where they assert the new wording. The two guard tests pass there: they check where the sentence stands, not its words.
- On the head 66b1043: the new module alone, `25 passed`.

### Targeted runs on the head 66b1043, BASE 396c0ff

- Set A, 29 files: every `tests/test_family*.py` and `tests/test_validate_family*.py`, plus `test_bump_leg.py`, `test_bump_leg_dry_run_tracking.py`, `test_bump_leg_dry_run_truth.py`, `test_bump_leg_paste_lines.py` and `test_update_shape_branch_any_directory.py`. Result: `1016 passed, 20 skipped in 511.01s`.
- From set B: `test_repo_hygiene.py`, `test_agents_md_codes.py`, `test_readme_sections.py` and `test_cli_reference.py`. Result: `210 passed in 15.73s`. The fix round changes no template other than `validate-family.py`'s text, so the rest of set B (the 27 files of the first round) is not re-run.
- Every skip is a platform skip that was there before this change (a case-ignoring disk, a Windows default, powershell.exe), or a template-quoting skip in `test_family_init_values.py`.

A real holder `Orbit`, made with `family.py init`, and a member `Atlas`, scaffolded with `scaffold-project.py --local-remote-dir`.

- **On BASE 396c0ff** (first round): `add` refuses with `switch -c family/add-atlas`. Typed as printed, that gives `fatal: a branch named 'family/add-atlas' already exists`, exit 128, and the remedy says nothing more. The validator's `member-gitlink-absent` remedy prints the same line, with the same result.
- **On the head, an unmerged act** (`probe-atlas.sh`, a branch holding a commit of its own): the refusal prints the new sentence. The same command with `switch` for `switch -c` gives `Switched to branch 'family/add-atlas'`, exit 0, at the earlier commit. `add` then exits 0, its NEXT pushes `family/add-atlas`, and its commit's parent is the earlier commit. The validator carries the same sentence.
- **On the head, `main` moved** (`probe-d.sh`): the printed line fails (128). With another name: `add` exits 0, `git merge-tree --write-tree main family/add-atlas-2` exits 0, `family ok: Orbit (orbit), 2 member(s)`. Going back instead: `add` exits 0, and `git merge-tree --write-tree main family/add-atlas` exits 1 with the two conflicts in decision 2.
- **On the head, a detached HEAD with a commit** (`probe-detached.sh`): the printed line fails (128). With another name, `git branch --contains` names `family/add-atlas-2`. Going back with `switch`: git warns it is leaving 1 commit behind, and no branch contains it.

No row needs real GitHub.

Each change below was made alone in a scratch clone of the head, then the new module was run (and, for the validator changes, the two other files that pin the sentence), and the file was put back. Every change that alters behaviour makes at least one new test fail:

| Change | Result |
|---|---|
| `family.py` `BRANCH_LEFT` back to the first round's words | 12 failed: the six refusal cases, the three dry-run cases, both new S1 tests, `test_the_two_tools_say_the_same_words` |
| `family.py` `BRANCH_LEFT` one clause dropped (`only if`) | 12 failed, the same tests |
| `_checked_branch` remedy with no sentence | 8 failed: the six refusal cases and both new S1 tests |
| sentence printed above the `switch -c` line, not under it | 8 failed: the same eight |
| `_branch_said` (dry run) with no sentence | 3 failed: `test_a_dry_run_on_the_tracking_branch_says_it_too` [add, bump, remove] |
| `_switch_command` prints `switch -C` | 11 failed, both new S1 tests among them: the printed line no longer fails `already exists` |
| validator `BRANCH_LEFT` back to the first round's words | 12 failed in the three files, `test_the_two_tools_say_the_same_words` among them |
| validator `member-gitlink-absent` with no sentence | 5 failed: its two typed-as-printed cases, the remedy test, the guard and its control |
| validator `member-duplicate-id` with no sentence | 4 failed: its two typed-as-printed cases, the guard and its control |
| validator `member-gitlink-unnamed` with no sentence | 8 failed: its two typed-as-printed cases, the four `GITLINK_REMEDY` cases, the guard and its control |
| **S2:** a fourth remedy added that names `_switch_line` and does not end with the sentence (built by a helper, as #634's `_lockstep` does) | 2 failed: the guard and its control, and nothing else in the three files |
| **S2:** the same fourth remedy ending with `{BRANCH_LEFT}` | 79 passed |
| `init` NEXT STEPS branch back to `<project>`; its `--member` lowercased | 1 failed each: `test_init_next_steps_spell_the_branch_as_its_member` |
| AGENTS.md, AGENTS-shape.md, holder README: branch back to `<project>` (and AGENTS.md's `--member`) | 1 failed each: `test_each_doc_spells_the_branch_as_its_member` for that doc |

The other hunks change only docstrings and comments (`_checked_branch`, `_branch_said`, `_print_next_steps`, `_switch_line`, and the comments above the two constants). They change no behaviour, so no test can catch reverting them.

| Ref | Result |
|---|---|
| origin/main f6376d7 (#614 landed; main has moved since BASE through #625, #583, #596) | clean, tree eb91b600. A committed merge of the head with it, e26dca8c, ran set A and #625's `test_family_bump_to_local_only.py`: `1024 passed, 20 skipped in 500.52s` |
| #620 a2b4f89 | clean (it conflicted in `adopt-project.py` in the first round; it no longer does) |
| #622 227bc3b (lane 2, #609, `scripts/family.py`) | clean |
| #626 207d4e1 (lane 4, `scripts/family.py`) | clean |
| #630 82f9403, #631 9733547, #632 86c6b9c, #633 f7f5de5, #635 2c0b157, #636 4aade9f | clean |
| #638 64e6621 | clean |
| #634 40a85e1 (lane 2, #610: `_lockstep` prints a fourth `switch -c`) | clean, and S2 fires on it. A committed merge, 4d1a7161: the new module, `test_validate_family_branch_step.py` and #634's `test_pinned_copy_text.py` give `2 failed, 86 passed`. The two failures are the guard, `assert [124] == []` (line 124 of the merged file is `_lockstep`'s return), and its control. With one line added to `_lockstep`, `f"moving one alone is what this refuses. {BRANCH_LEFT}"` in place of the plain string, the same merge gives `306 passed` over the nine files that read the validator or the lockstep rule (`test_validate_family*.py`, `test_family.py`, `test_family_tracking_branch.py`, `test_pinned_copy_text.py` and the new module). So the second PR to land needs that one line and nothing else. |
| #639 6f938ed (lane 5, #611) | conflicts in the same one sentence, in the same two places: the end of the `member-gitlink-unnamed` remedy text in `validate-family.py` (`_check_gitlinks_named`), and the `GITLINK_REMEDY` constant in `tests/test_validate_family_unnamed_mounts.py`. #611 adds "and commit that removal, since `family.py add` refuses ..." and this PR appends `BRANCH_LEFT`. Resolved as in the first round, keeping #611's clause and appending ` {BRANCH_LEFT}` in the validator and `+ BRANCH_LEFT` in the test constant, in a committed merge (92602308): `scripts/family.py` merged cleanly, and the six test files that either PR changes or pins gave `157 passed`. Neither branch was resolved. |

- No compound `||` line and no state check: see decision 1.
- No README.md edit: no README sentence becomes false, because no new kind of line is printed.
- The docs do not mention the exists case. AGENTS.md is at its cap, and the tools print the sentence where the failure happens.
- The `switch -c` in `init`'s NEXT STEPS gets no sentence: a holder `init` just made has no branch an earlier act could have left.
- **A branch checked out in another worktree (N1).** Where `family/add-atlas` is checked out in another worktree of the holder, `git switch family/add-atlas` gives `fatal: 'family/add-atlas' is already used by worktree at '<path>'` (exit 128), so the going-back half of the sentence does not work there. Git names the worktree, and another name works (`probe-n1.sh`: `switch -c family/add-atlas-2` exits 0). The sentence is not made longer for it.
- I could not run Windows PowerShell or macOS here. The tests read `family.py`'s lines with `host_words`, which parses PowerShell's quoting on Windows. They make the earlier branch with `commit-tree` and `update-ref`, move `main` with the same two, write no file with `write_text` and compare nothing CRLF-sensitive. `test_another_name_works_where_main_has_moved_since` runs `git merge-tree --write-tree`, which needs git 2.38 or newer. No CI job checks Windows or macOS.

- **bump-leg.py: the `git switch -c bump/<role>-<sha12>` remedy fails `already exists` when an earlier bump left that branch.** `_switch_command` (scripts/bump-leg.py:1124) prints the line for the two refusals and the dry run's closing hint. Like #607, it says nothing about a branch that is already there.
- **setup-project.py: the family `git -C <holder> switch -c family/add-<project>` line has the same gap.** The NEXT lines a scaffold into a family folder ends with (setup-project.py:2358) print it with no word on an existing branch. It matters only when an earlier attempt left that branch.

- L2-46 ([#459 comment](#459 (comment)))
- L2-45 ([#459 comment](#459 (comment)))

Review: rv607 found 0 blockers, 2 should-fix and 7 nits on 6212c31 (CHANGES NEEDED), fixed in 66b1043; the re-verify rv607b found 5 nits on 66b1043 (APPROVE WITH NITS), of which nits 1, 3 and 4 and the docstring half of nit 5 are fixed in a277695, and nit 2 is left. CI (Brett Heap's ruling 27, with his fast-refresh ruling of 2026-10-15T22:48:35Z): H0 a277695 passed tests (Linux), tests-git-bash and SonarCloud; the head 62263d2 is a clean update-branch merge of main a524542 (over e041867, a clean merge of 5b29ee1), with SonarCloud, tests-git-bash and package green on it, and the local gate passed on the head itself: the family and validator set, 1016 passed (20 skipped), and the hygiene, AGENTS.md-code, README-section and CLI-reference sets, 222 passed. Landed on Brett Heap's word of 2026-10-16T11:21:49Z, "Merge #637 when its turn comes".

Closes #607

Lane: openreposhape-5 (openRepoShape-5)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@brettheap brettheap mentioned this pull request Oct 16, 2026
Merged
brettheap pushed a commit that referenced this pull request Oct 16, 2026
Brett Heap @claude
docs/handbook.html and docs/release-notes/v1.1.0.md: step 3's Git Bas…
ddd3c5f 
…h route claims only that the one line runs, under a Windows heading that names it, and the notes carry #620, #596's `ln -s` fact, headings that fit their entries, whose YAML reader it is and who made the environments (RV630 round 3: SHOULD 1-2, nits 1-5)

The handbook:
- SHOULD 1: "In Git Bash, the one-line install runs too:", where it said
  "works as on Linux", which #596 does not support: `ln -s` makes a copy
  there and `chmod` changes nothing.
- nit 1: the step no longer repeats the panel's definition of Git Bash,
  and states the caveat once, without pointing at the panel as well.
- nit 2: the Windows tab's heading names the third way, "Install with
  pipx, fetch the flow, or use Git Bash's one line".

The release notes:
- SHOULD 2: the Git Bash known limit says, as #596 and the launcher's
  comment do, that `ln -s` makes a copy there unless
  `MSYS=winsymlinks:nativestrict` is set, and a copy has no
  `openRepoShape.ref` beside it, so it follows main, not the installed
  release; link it with that setting, or put `~/.local/bin` on `PATH`.
- nit 3: "update-shape.py, bump-leg.py and a project's own scripts" and
  "scaffold, setup, family and the shared readers"; no entry moved.
- nit 4: the YAML reader is the standard's own, in `repo_shape.py`, which
  the tools use to read `project.yaml` and the pin files.
- nit 5: the release process's acts made once say who made which: the
  trusted publishers are Brett Heap's to make; lane openRepoShape-3 made
  the environments and the tag ruleset as brettheap on his word.
- #620 (#601), merged from main 879d804, under adopt-project.py; the list
  is current to main 879d804; the counts (67 pull requests; 76 of 104
  milestone issues closed at 12:43Z) and the open list (28) are refreshed,
  and stay placeholders.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
brettheap added a commit that referenced this pull request Oct 16, 2026
@brettheap @claude
openRepoShape in Git Bash: the machine: row finds python, a drive…
35133f2 
…-letter `$OPENREPOSHAPE_REPO` is a path, a Windows-spelled `$OPENREPOSHAPE_BIN_DIR` is respelled or refused, and `tests-git-bash` runs #598's installer cases (#649) (#656)

#596's Git Bash follow-ups, the five lines of #649. Two commits on main a524542: **d91b3144**, the fix, and **e85573ac**, fix round 1 from rv649's review. Together they change `openRepoShape`, `.github/workflows/tests.yml` and `tests/test_openreposhape_command.py`, and nothing else. `git diff --numstat`, d91b314: `openRepoShape` +42/-4, `tests.yml` +6/-1, the test file +182/-7. e85573a: +9/-6 (comments only), +3/-2 (a comment only), +56/-27. README, the handbook and `docs/cli.md` are unchanged: every sentence about these blocks stays true (below).

### Fix round 1 (rv649)

rv649 found the launcher's code correct and asked for changes: 0 blockers, 1 should, 6 nits. e85573a answers each point. It changes no line of the launcher's code and no command of the workflow: three comments and the tests.
- **SHOULD-1, the `D:/…` arm had no test.** Both BIN_DIR tests now run over `D:\tools\bin` and `D:/tools/bin`, and `fake_cygpath` takes the typed value. On Windows they use `str(...)` and `.as_posix()` of a path under `tmp_path`. With the arm dropped the suite stayed green (91 passed); now 5 cases fail.
- **NIT-1, the refusal's drive-answer arm had no test.** A third refusal case: a `cygpath` that answers `D:/tools/bin` with exit 0. With that arm dropped the suite stayed green; now 2 cases fail.
- **NIT-2, a `python` that is Python 2, or older than 3.9, reads as present.** Named as a cost in decision 1 and in the comment above `machine_report`. No code change: `--preflight` still refuses those machines.
- **NIT-3, the refusal's reason was false in Git Bash with `cygpath` off `PATH`.** Git Bash does read `D:\…` as a drive. The comment in `install_commands` and decision 3 now give the true reason.
- **NIT-4, the job's opening comment named two files.** It names the three.
- **NIT-5, on Windows the refusal test's value was a real `D:` drive path.** It is now a path under `tmp_path`, and the assert names that value, so a refusal that regressed would place the command where the test looks.
- **NIT-6, four claims.** Fixed in this body: "rows 1-3 are checked through the tests" (now says what runs), the clone URL for each slash (`C:\src\…` gave `https://github.com/C:\src\openRepoShape.git`), the Store stub clause (dropped, see decision 1) and the report's diffstat totals (the exact `--numstat` counts are at the top). d91b314's own commit message keeps its `....` typo and its one-URL sentence in history; the squash message is this body.
- **Composition and merge table.** Refreshed against origin/main 879d804 (below). #630 no longer conflicts.
- **Checklist candidate 3**, from rv649, is added below.

### The fix

**1. The `machine:` row for Python** (`machine_report`).
- Before: the block asked `command -v python3` and nothing else. Where Python came from python.org, Git Bash has `python` and no `python3`, so the row said `python3 MISSING` and printed the line pointing at `--preflight`, which then passed with `python`.
- Now: it asks for `python3`, then `python`, in `find_python`'s order. When only `python` answers, the row says `python3          present, as python`, and nothing points at `--preflight` for it. With neither, it says `MISSING`, as before. With `python3`, it says `present`, byte for byte as before.

**2. A drive-letter `$OPENREPOSHAPE_REPO`** (`shape_clone_url`).
- Before: `C:/src/openRepoShape` and `C:\src\openRepoShape` were read as an owner/name, so setup.sh's clone and `--doctor`'s were handed `https://github.com/C:/src/openRepoShape.git` for the first and `https://github.com/C:\src\openRepoShape.git` for the second.
- Now: a letter, a colon and then `/` or `\` is a path, and goes through as it is, as `/…` and `.…` do. No owner/name holds a colon. The package's own `clone_url` (`src/openreposhape/standard.py`, `DRIVE_RE`) already read a drive letter this way.

**3. A Windows-spelled `$OPENREPOSHAPE_BIN_DIR`** (`install_commands`).
- Before: `--install` named the directory as typed. With `D:\tools\bin` it printed `installed at D:\tools\bin/openRepoShape` and `export PATH="D:\tools\bin:$PATH"`, which the drive's colon splits in two. It also never found the directory on a `$PATH` that holds `/d/tools/bin`, so it printed that line every time.
- Now: a drive-letter value, in either slash, is spelled again with `cygpath -u`, which Git Bash has, before anything is checked or placed. Every line then names `/d/tools/bin`, and the PATH note appears only when that directory is not on `$PATH`.
- Where no `cygpath` answers (none on PATH, it fails, or it answers a drive spelling again), the value is refused before anything is placed: "--install would place this command in 'D:\tools\bin', which is spelled for Windows, and no cygpath here spells it the way bash does, so the directory could not go on $PATH: the drive's colon splits it. Nothing was placed. Set $OPENREPOSHAPE_BIN_DIR to the directory as this shell spells it, then run this again."

**4. `tests-git-bash` runs `tests/test_install_sh_filter_repo.py`.** That file holds #598's uv install, the two readinesses and the pasted next steps, which ran on Linux only, while README says Git Bash runs step 3's one line "tested in CI". It is the third path on the job's pytest line, with a comment saying the installer's suite is two files. The job's other lines, the header's "the launcher's and the installer's suites, and nothing else" and #630's release-notes sentence of the same meaning stay true.

**5. The stale docstring.** `test_a_ref_the_doctor_would_check_out_is_validated` said the refusal "has to arrive before any clone does". The command clones first, then checks the ref, and refuses before `git checkout` is handed it. The docstring now says that. The order is unchanged.

- **Line 1: `command -v` for both names, and no version check.**
  - The block promises to execute nothing but `gh auth status`, and `test_the_machine_report_runs_no_installer` holds it to that: every fake on its PATH logs a run. Running `find_python`'s check would break that promise.
  - What answers is therefore never asked its version, and that has a cost. The Microsoft Store's `python3` stub reads as present, as macOS's Command Line Tools stubs for `python3` and `git` already do (setup.sh's comment at :41-47). That is not new: the base asked `command -v python3` too, and the Store installs its `python.exe` and `python3.exe` aliases together, so `python3` answers first.
  - What is new is a `python` that is Python 2, or older than 3.9, where there is no `python3`. On the base such a machine said `python3 MISSING` and printed the `--preflight` pointer. Now it says `present, as python` and prints no pointer. It is rare (CentOS 7, macOS 10.14 or older, Python 2.7 from python.org), and `--preflight` still refuses it with "no Python 3.9 or newer on this machine (tried python3, python)". The comment above `machine_report` says so.
  - The row keeps its name `python3`, and the state carries the name that answered, in the form `gh`'s row already uses (`present, logged in`). So README's sentence ("`git`, `gh` and whether it is logged in, `python3`, and `git-filter-repo` … each `present` or `MISSING`") and the handbook's stay true, and README is not edited. Labelling the row `python` would have made both false in Git Bash.
- **Line 3: respell, and refuse only where respelling is not possible.** Respelling keeps a Git Bash user's value working: `cp`, `mkdir` and the record took the Windows spelling already, and only the printed lines were wrong. Where no `cygpath` answers, nothing in the command can spell the value as bash's `$PATH` needs it: in Git Bash with `cygpath` off `PATH` the drive is real but its colon still splits `$PATH`, and on Linux `D:\tools\bin` is a relative directory with a colon in its name. No `$PATH` line could work there, so it refuses. A `cygpath` that answers a drive spelling again is refused alike.
- **The tests' `install_with_machine` now names its directory with `bash_path`.** Its `$PATH` holds only the programs `--install` runs, and no `cygpath`. On Windows the old `str(bin_dir)` is a drive path, which would now be refused. Off Windows, `bash_path` changes nothing. Other tests that pass `str(...)` keep the full PATH, so on Windows they now go through Git Bash's own `cygpath`.
- **`run_cmd` takes a `cwd`.** On the base, and under a mutation, the new BIN_DIR tests' `D:\tools\bin` is a relative directory. With `cwd=tmp_path` it lands in the test's own directory, never in the checkout.
- **Both BIN_DIR tests run over both slashes** (`BIN_DIR_SPELLINGS`, `typed_bin_dir`). Off Windows the typed value is the fixed `D:\tools\bin` or `D:/tools/bin`. On Windows it is a path under `tmp_path`, so neither test can place a command on the machine's own `D:` drive.

New, in `tests/test_openreposhape_command.py`, 27 cases:
- `test_the_machine_report_finds_a_python_by_either_name`: `python` alone, both, neither (3).
- `test_a_windows_spelled_bin_dir_is_spelled_the_way_bash_spells_it`: not on `$PATH`, on `$PATH`, each in both slashes (4). On Windows it is a real drive path (`str(bin_dir)` or its `as_posix()`) and Git Bash's own `cygpath`; elsewhere a fake `cygpath` answers as that one would.
- `test_a_windows_spelled_bin_dir_is_refused_where_no_cygpath_spells_it`: no `cygpath`, a `cygpath` that fails, a `cygpath` that answers `D:/tools/bin`, each in both slashes (6), on the machine report's own `$PATH`.
- `test_a_clone_is_handed_a_path_or_url_as_it_is`: owner/name, URL, scp, POSIX path, `C:/…`, `C:\…` and `d:\…`, each through setup.sh (a setup.sh that prints `$OPENREPOSHAPE_REPO`) and through `--doctor` (a `git` that prints the URL it is handed and fails) (14). Nothing is cloned or fetched.

**On the base a524542** (this head's test file over the base's command): **17 failed, 80 passed** in 62.32s. The failures are exactly the new cases that need the fix: `python-alone`, the four respelling cases, the six refusal cases and the six drive-letter cases. The other 10 new cases pass there too, as they should.

**On the head e85573a** (Linux, `dirty=0`):
- `tests/test_openreposhape_command.py`, `tests/test_install_sh.py`, `tests/test_install_sh_filter_repo.py`, `tests/test_openreposhape_package.py`: **220 passed** in 175.18s. The package suite imports 13 of the launcher's cases and swaps `run_cmd`, so it is in the set.
- `tests/test_repo_hygiene.py`, `tests/test_workflow_concurrency.py`, `tests/test_release_workflow.py`: **138 passed** in 14.46s.
- The head merged with main 879d804 (a probe commit, b6cfafe3): the launcher's, the two installer files, the package suite and `tests/test_repo_hygiene.py`, **297 passed** in 188.95s.
- **The three files `tests-git-bash` runs, with Windows' `write_text` emulated**: a plugin made every `Path.write_text` in the test process write CRLF, as it does on `windows-latest`. **162 passed** in 121.06s (97 + 47 + 18). A probe test shows the plugin takes effect (it passes with the plugin and fails without it).
- **actionlint 1.7.12**, with shellcheck on PATH, on `tests.yml` alone and on the four files the CI job names: exit 0.

d91b314's own `tests-git-bash` run was green on `windows-latest`. It ran the first round's 21 new cases and `tests/test_install_sh_filter_repo.py` there, so Git Bash's own `cygpath` answered the backslash respelling on a real drive path, and the five existing tests that pass `str(...)` and now go through it passed. What was checked, and what was not:
- **Checked, from #596's Windows runs (113 passed on 5f001de, and its probes):** a fake that Python writes with `#!/bin/sh` runs under Git Bash with no mode bits, and `command -v` finds it. A script piped in text mode reaches Git Bash's bash as CRLF, and bash drops the CR. A `$OPENREPOSHAPE_BIN_DIR` set from Python reaches bash unconverted: #596's probe 4 printed `D:\a\_temp\…\bin/openRepoShape`, which is why the respelling now runs in those tests.
- **Checked on Linux:** LF bytes (the CRLF emulation above). No assert in the test file compares a path bash printed with a Python path.
- **Not checked, until e85573a's own run:** on Windows, the slash spelling (`as_posix()`) through Git Bash's real `cygpath`, the refusal's values under `tmp_path` on the machine report's `$PATH`, and the new drive-answer case. If one fails there, its log shows the typed value and the directory.

One script ran each row against the base's command and the head's, offline, with a `gh` stub first on PATH. Row 3's slash lines ran again for this round.

| Row | Base a524542 | Head e85573a |
|---|---|---|
| 1. PATH with `git`, a logged-in `gh`, `python`, `git-filter-repo`, no `python3` | `python3          MISSING`, then `run: openRepoShape --preflight …`; the log holds only `gh auth status` | `python3          present, as python`, no `run:` line; the log holds only `gh auth status` |
| 2. `OPENREPOSHAPE_REPO=C:/src/openRepoShape` | setup.sh clones `https://github.com/C:/src/openRepoShape.git`; the doctor's `git clone` too | `C:/src/openRepoShape`, both |
| 2. `OPENREPOSHAPE_REPO=C:\src\openRepoShape` | `https://github.com/C:\src\openRepoShape.git`, both | `C:\src\openRepoShape`, both |
| 2. `OPENREPOSHAPE_REPO=acme/openRepoShape` | `https://github.com/acme/openRepoShape.git` | the same |
| 3. `OPENREPOSHAPE_BIN_DIR='D:\tools\bin'`, no `cygpath` | exit 0, `installed at D:\tools\bin/openRepoShape`, `export PATH="D:\tools\bin:$PATH"` | exit 2, the refusal above, nothing placed |
| 3. `OPENREPOSHAPE_BIN_DIR='D:/tools/bin'`, no `cygpath` | exit 0, `installed at D:/tools/bin/openRepoShape`, `export PATH="D:/tools/bin:$PATH"` (on Linux, a relative directory named `D:` in the working directory) | exit 2, the same refusal with `'D:/tools/bin'`, nothing placed |
| 3. the same, a fake `cygpath -u` answering `<dir>/d/tools/bin` | the same as with none: `cygpath` is never asked | exit 0, `installed at <dir>/d/tools/bin/openRepoShape`, `export PATH="<dir>/d/tools/bin:$PATH"` |
| 4. `tests-git-bash`'s pytest line | two files | three files |
| 5. the docstring | "the refusal has to arrive before any clone does" | "clones this checkout first, then checks the ref" |

Rows 1-3 need Windows to be real: there, `python` is a real python.org install, and `cygpath` and the drive letter are Git Bash's own. On Linux they are fakes. The first Windows run runs rows 1-3's tests under Git Bash: row 3 with Git Bash's own `cygpath` on a real drive path, rows 1 and 2 with a fake `python` and a fake `git`, so a real python.org install and git's own reading of `C:/…` stay unchecked.

Each row reverts one hunk of the launcher, or one part of the BIN_DIR hunk, in a throwaway clone, then runs the 27 new cases.

| Hunk reverted | Result | Failing cases |
|---|---|---|
| none (the head) | 27 passed | — |
| `shape_clone_url`'s drive-letter arm | 6 failed | the six drive-letter cases, setup.sh and doctor |
| `machine_report`'s `python` arm | 1 failed | `python-alone` |
| the BIN_DIR block, whole | 10 failed | the four respelling cases and the six refusal cases |
| the `cygpath -u` call (always refuse) | 4 failed | the four respelling cases |
| the refusal (keep the value as typed) | 6 failed | the six refusal cases |
| `\|\| spelled=""` after the `cygpath` call | 2 failed | `cygpath-fails`, both slashes: `set -e` exits with `cygpath`'s status, 1, not the refusal's 2 |
| **the `D:/…` arm of the drive case (SHOULD-1)** | 5 failed | the two slash respelling cases and the three slash refusal cases (was green) |
| the `D:\…` arm of the drive case | 5 failed | the same five, backslash |
| **the refusal's drive-answer arm, `[A-Za-z]:*` (NIT-1)** | 2 failed | `cygpath-answers-a-drive`, both slashes (was green) |
| the refusal's empty-answer arm, `""` | 4 failed | `no-cygpath` and `cygpath-fails`, both slashes |
| `--` dropped from `cygpath -u -- "$dir"` | 4 failed | the four respelling cases: the fake answers only `-u -- <value>` |
| the respelling after the placement, not before | 4 failed | the four respelling cases |

Not probed by a test: the `tests.yml` line (CI configuration, checked by actionlint and by this PR's own Windows run), the docstring, and `install_with_machine`'s `bash_path` (identity off Windows; on Windows it is what keeps four machine-report tests from the new refusal).

| Against | Result |
|---|---|
| origin/main 879d804 (d4a7fab, then 879d804, since the last table's 95780dd) | **clean**. Of this PR's files, the three suites', README and the handbook, only `tests/conftest.py` has moved since the base a524542 (new helpers for setup-project's tests), and nothing since the last table's 95780dd. The head merged with main (a probe commit, b6cfafe3) passes the suites below. |
| lane 3's #630 61b3907 | **clean**. It conflicted at ca5c49f, at the `tests-git-bash` pytest line, because its base was older than main's #590; its head now holds main d4a7fab, and it does not change `tests.yml`. It changes `AGENTS.md`, README, `adopt-project.py`, the handbook, `docs/cli.md`, the release notes and four test or render files, none of which this PR touches. |
| #620 9f2b67c, #621 10dda17, #622 55666f3, #623 fc08a28, #627 83ca2db, #628 d64252a, #631 21bdac8, #634 b7472df, #636 30a52c0, #637 62263d2, #638 b393e1f, #639 08b6245, #642 1a42df4, #643 1fe3764, #644 733f853 | **clean** (#623 changes `tests/conftest.py`; #627 changes README and the handbook) |
| #641 e87fcb0 | conflicts in `scripts/family.py`, and so does #641 against main alone: its own conflict, not an overlap with this PR. |
| lane 5's `fix/645-fixture-copy-maintenance-race` accc7d2, `fix/646-add-member-variant-remedy` 79754b9, `fix/647-branch-left-bump-leg-setup` be1bff9 (#657), `fix/648-bootstrap-and-gate-order` 852c5c4 | **clean**, all four |

- **The Store stub check.** See the decision on line 1. `--preflight` is where a stub is told apart.
- **`install.sh`'s own lines.** It names a Windows-spelled `$OPENREPOSHAPE_BIN_DIR` as typed in its `preflight:` and `done:` lines, though the command it installs now prints `/d/…`. #649 names `--install`'s PATH note, and `install.sh` prints no PATH line. Checklist candidate 1.
- **`--help`.** Its `$OPENREPOSHAPE_REPO` and `$OPENREPOSHAPE_BIN_DIR` lines stay true, so `docs/cli.md` is not regenerated.
- **`D:`, `D:tools` and UNC values.** Checklist candidate 3.

1. **`install.sh` echoes a Windows-spelled `$OPENREPOSHAPE_BIN_DIR` as typed.** It builds `target="$bin_dir/openRepoShape"` from the raw value, so in Git Bash with `D:\tools\bin` its `preflight:` and `done:` lines say `D:\tools\bin/openRepoShape`, while the command's own lines say `/d/tools/bin/openRepoShape`. Both spellings work in Git Bash, so nothing breaks. On a machine with no `cygpath`, the command's `--install` now refuses the value, and `install.sh` stops with "the <version> openRepoShape's --install refused (exit 2); its own refusal above says why", which is right but could refuse earlier, before the fetch.
2. **The PATH note is not quoted for every directory.** `--install` prints `export PATH="$dir:$PATH"` with the directory between double quotes as it is. A directory holding `"`, `$`, a backquote or `\` prints a line that does not do what it says, and one holding `:` cannot be on `$PATH` at all. A drive letter was the one case a person in Git Bash meets by default; the rest need a deliberately odd directory name.
3. **Two kinds of value slip past both new arms** (rv649). `$OPENREPOSHAPE_BIN_DIR` set to `D:` or `D:tools` matches neither respelling arm, so it is kept as typed and prints `export PATH="D:tools:$PATH"`, as on the base. A UNC `\\server\share\…`, as `$OPENREPOSHAPE_BIN_DIR` or `$OPENREPOSHAPE_REPO`, is never respelled (the PATH note's `\\` collapses) or becomes a github.com URL. The package's `clone_url` passes a UNC path through on Windows (`os.path.isabs`).

Review: rv649 found 0 blockers, 1 should-fix and 6 nits on d91b314 (CHANGES NEEDED); the fix round e85573a answers all seven, so both mutations that survived now fail a test, and lane 5's coordinator checked it. CI (Brett Heap's ruling 27, with his fast-refresh ruling of 2026-10-15T22:48:35Z): H0 e85573a passed tests (Linux), tests-git-bash (windows-latest) and SonarCloud; the head 022bd50 is a clean update-branch merge of main 8062810, with SonarCloud, tests-git-bash and package green on it, and the local gate passed on the head itself: the launcher, installer and package set, 220 passed, and the hygiene, workflow and README-section set, 214 passed. Landed on Brett Heap's word of 2026-10-16T13:07:34Z, "merge #656 and #657 when green".

Closes #649

Lane: openreposhape-5 (openRepoShape-5)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@brettheap brettheap mentioned this pull request Oct 16, 2026
Closed
3 tasks
brettheap pushed a commit that referenced this pull request Oct 16, 2026
Brett Heap @claude
README.md, the handbook and the v1.1.0 notes: the adopted repository …
6fd33a9 
…KEEPS ITS NAME (which `--project` must be), ITS IDENTITY AND ITS FULL HISTORY, and the notes are current to main de92614, with seven more pull requests, lane 2's re-run-`plan` line, lanes 4's and 1's known limits, Developer Mode for a Git Bash symlink and the trusted publishers (#563, L4-47)

- L4-47 (#457, lane 4 on #630 at 14:13:32Z): README.md:771-772 and
  docs/handbook.html:1276-1277 say "it KEEPS ITS NAME (which `--project`
  must be), ITS IDENTITY AND ITS FULL HISTORY, and becomes the assembly
  root". Two lines each, no line added: README.md is still 1473, its cap.
  The § Adopting marker moves to b23e9f98, text and marker; no other
  marker moves.
- The notes, "What changed since v1.0.1": #628 (#600), with lane 2's line
  for a plan written before v1.1.0 (#473, 12:53:40Z) after it, and #621
  (#602) under adopt-project.py; #657 (#647) under update-shape.py,
  bump-leg.py and a project's own scripts; #639 (#611) under scaffold,
  setup, family and the shared readers; #656 (#649), #698 (#679) and #627
  (#606) under install, CI and the docs. Every pull request since bfed143
  is cited (`git log --first-parent bfed143..de92614`, 74).
- Known limits: lane openRepoShape-4's ten lines (#630
  issuecomment-6217406337: L4-05, -06, -07, -08, -17, -43, -45, -54, -24,
  -156) and lane openRepoShape-1's twenty-six D9 lines (#457
  issuecomment-6214768828), as two lists, one sentence each; and the Git
  Bash limit says that Windows lets a non-administrator make a symlink
  only in Developer Mode, as #596 does.
- How this release is cut: the trusted publishers are filled from Brett
  Heap's 13:04:43Z ("the pypi are added") and 13:07:56Z ("they match what
  you listed").
- The counts (74 pull requests; 83 of 135 milestone issues closed at
  17:16Z), the "current to main" sha and the open list (52) are at main
  de92614, still placeholders for tag time.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

1 participant

@brettheap