Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 65 additions & 0 deletions scripts/sync-master-from-api.py
Original file line number Diff line number Diff line change
Expand Up @@ -375,6 +375,50 @@ def rev_parse(ref: str) -> str:
return r.stdout.decode().strip() if r.returncode == 0 else ""


def worktree_state(head: str, cwd: str | None = None) -> tuple[str, str]:
"""Whether this checkout's files now hold `head`, or whether that cannot be asked.

`git update-ref` moves a *ref*. It does not touch the index or the working tree,
so after this tool ends the refs name the new commit while every command that
opens a file still answers from the previous one: measured 2026-11-17, a tree
whose `HEAD` declared `0.3.58` answered `__version__ = "0.3.57"`, and
`git status` listed the difference as ten staged modifications. No downstream
reading catches it, because `git log`, `git rev-parse HEAD` and
`git show HEAD:<path>` are all correct - only comparing them to a file notices.

Four answers, and "could not be asked" is one of them:

* `match` - `HEAD` is `head`, and the index and working tree hold its content;
* `differs` - `HEAD` is `head` and N **tracked** path(s) differ from it. This tool
cannot tell its own stale index from a caller's uncommitted edits, so it says that
rather than choosing. An untracked file is not counted: it is in no commit, so it
cannot differ from one, and `git reset --hard HEAD` would not remove it - naming it
would make the remedy false for the cause it reported (issue #2939's review);
* `elsewhere` - `HEAD` is some other commit, named, because that is what the
files are; the ref this tool moved is not the one checked out;
* `unmeasured` - a git invocation failed, so no answer exists. Never a match.

It **measures and never repairs**: bringing the two into step discards local
edits, which is the caller's call and not a side effect of a sync.
"""
r = subprocess.run(["git", "rev-parse", "-q", "--verify", "HEAD"], capture_output=True,
text=True, encoding="utf-8", errors="replace", cwd=cwd)
if r.returncode != 0:
return ("unmeasured", "`git rev-parse HEAD` failed: " + (r.stderr.strip() or "no output"))
current = r.stdout.strip()
if current != head:
return ("elsewhere", current[:7])
s = subprocess.run(["git", "status", "--porcelain", "--untracked-files=no"],
capture_output=True,
text=True, encoding="utf-8", errors="replace", cwd=cwd)
if s.returncode != 0:
return ("unmeasured", "`git status --porcelain` failed: " + (s.stderr.strip() or "no output"))
changed = [line for line in s.stdout.splitlines() if line.strip()]
if changed:
return ("differs", str(len(changed)))
return ("match", "")


def repo_from_origin() -> str:
# encoding="utf-8": the origin URL is echoed back in SystemExit below, and a
# clone directory may carry a non-ASCII byte; the locale codec would raise
Expand Down Expand Up @@ -505,6 +549,27 @@ def main() -> int:
for ref in (f"refs/heads/{args.ref}", f"refs/remotes/origin/{args.ref}"):
subprocess.run(["git", "update-ref", ref, head], check=True)
print(f"updated refs/heads/{args.ref} and refs/remotes/origin/{args.ref} -> {head[:7]}")

# The refs are right from here on; the *files* are not, until someone says so.
# `update-ref` touches neither the index nor the working tree, so a caller that
# reads a file next reads the previous commit's content while `git log` answers
# about the new one (issue #2939). Said here, once, in the run that moved them.
state, detail = worktree_state(head)
if state == "match":
print(f" the index and working tree hold {head[:7]}'s content")
elif state == "differs":
print(
f" note: {detail} path(s) differ from {head[:7]}. `git reset --hard HEAD` "
f"brings them into step, and it DISCARDS local edits - run it only if those "
f"differences are this run's doing, not work you have in progress"
)
elif state == "elsewhere":
print(
f" note: HEAD is {detail}, not {head[:7]} - the files in this checkout are "
f"{detail}'s content, and the ref this run moved is not the one checked out"
)
else:
print(f" note: whether the files hold {head[:7]} could not be measured - {detail}")
return 0


Expand Down
158 changes: 158 additions & 0 deletions tests/test_sync_master_from_api.py
Original file line number Diff line number Diff line change
Expand Up @@ -570,3 +570,161 @@ def fake_get(url: str) -> dict:
assert r.returncode == 0, f"{sha[:7]} is not readable as a tree: {r.stderr}"
assert _git("rev-parse", "refs/heads/master",
cwd=target).stdout.decode().strip() == c2


# ------------------------- the refs move, the files do not (issue #2939)


def _commit_file(repo: Path, text: str, message: str) -> str:
"""Commit `a.txt` with `text`, return the new HEAD sha."""
(repo / "a.txt").write_text(text, encoding="utf-8")
_git("add", "a.txt", cwd=repo)
r = _git("commit", "-q", "-m", message, cwd=repo, env=GIT_ENV)
assert r.returncode == 0, r.stderr
return _git("rev-parse", "HEAD", cwd=repo).stdout.decode().strip()


def _branch(repo: Path) -> str:
return _git("symbolic-ref", "--short", "HEAD", cwd=repo).stdout.decode().strip()


def test_a_moved_ref_leaves_a_worktree_that_differs_and_says_how_many_paths(tmp_path):
"""The state that made a synced tree answer from the previous commit.

`git update-ref` moves a branch and touches neither the index nor the working
tree, so after a sync the refs name the new commit while every command that
opens a file answers from the old one - measured 2026-11-17, when a tree whose
`HEAD` declared `0.3.58` answered `__version__ = "0.3.57"` and `git status`
listed the difference as ten staged modifications (issue #2939).

The reading must also have left the files alone: repairs that discard local
work are the caller's decision, never a side effect of measuring.
"""
mod = _load_module()
repo = _init_repo(tmp_path)
old = _commit_file(repo, "one\n", "first")
new = _commit_file(repo, "two\n", "second")

# The ordinary case first: the files and HEAD agree.
assert mod.worktree_state(new, cwd=str(repo)) == ("match", "")

# Now move the checked-out branch back, the way the sync moves it.
_git("update-ref", f"refs/heads/{_branch(repo)}", old, cwd=repo)

state, detail = mod.worktree_state(old, cwd=str(repo))
assert state == "differs", (state, detail)
assert detail == "1", detail
assert (repo / "a.txt").read_text(encoding="utf-8") == "two\n", (
"measuring the worktree must not rewrite it"
)


def test_a_head_on_another_commit_is_named_rather_than_called_stale(tmp_path):
"""`elsewhere` is its own answer: the files are the commit `HEAD` names.

A sync of a branch that is not the one checked out moves a ref the caller is
not standing on. Reporting that as "stale" would advise a reset that moves them
off their own branch, so the answer names the commit the files actually are.
"""
mod = _load_module()
repo = _init_repo(tmp_path)
old = _commit_file(repo, "one\n", "first")
new = _commit_file(repo, "two\n", "second")

_git("update-ref", "refs/heads/side", new, cwd=repo)
assert _git("checkout", "-q", "side", cwd=repo).returncode == 0

state, detail = mod.worktree_state(old, cwd=str(repo))
assert state == "elsewhere", (state, detail)
assert detail == new[:7], (
"the answer names the commit the files actually are - after checking out "
"`side`, that is the newer commit, not the one the caller asked about"
)


def test_an_untracked_file_is_not_a_difference_from_the_commit(tmp_path):
"""An untracked file is in no commit, so it cannot differ from one.

`git status --porcelain` lists untracked paths by default, so a tree whose tracked
content and index hold `head` exactly, plus one scratch file, read `("differs",
"1")` and the run printed `1 path(s) differ from <head>`. The remedy it prints is
false for that cause as well: `git reset --hard HEAD` leaves untracked files alone,
so the caller runs it and the same warning returns on the next sync. Measured on a
probe repository: the default listing answers `?? scratch.txt`, and
`--untracked-files=no` answers nothing - the question this function is asking.

Both directions, because a fix that stopped counting tracked changes would pass the
first half alone.
"""
mod = _load_module()
repo = _init_repo(tmp_path)
head = _commit_file(repo, "one\n", "first")

(repo / "scratch.txt").write_text("unrelated\n", encoding="utf-8")
assert _git("status", "--porcelain", cwd=repo).stdout.decode().strip().startswith("??")
assert mod.worktree_state(head, cwd=str(repo)) == ("match", ""), (
"an untracked file is in no commit, so it cannot differ from one"
)

(repo / "a.txt").write_text("two\n", encoding="utf-8")
assert mod.worktree_state(head, cwd=str(repo))[0] == "differs", (
"a tracked modification still differs"
)


def test_a_git_that_cannot_answer_is_unmeasured_never_a_match(tmp_path, monkeypatch):
"""A git that cannot answer has not agreed. The family's standing rule.

Built from a failing `git`, not from "a directory outside any repository": on
the host this was measured on, `tempfile.gettempdir()` **is** the checkout, so
`git rev-parse` inside the temp directory answers that checkout's own HEAD and
the arm would assert `elsewhere` while looking like it tested `unmeasured`
(measured 2026-11-17). A stub cannot move with the host's temp settings.
"""
mod = _load_module()

class Failing:
returncode = 128
stdout = ""
stderr = "fatal: not a git repository (or any of the parent directories): .git"

monkeypatch.setattr(mod.subprocess, "run", lambda *a, **k: Failing())

state, detail = mod.worktree_state("0" * 40, cwd=str(tmp_path))
assert state == "unmeasured", (state, detail)
assert "not a git repository" in detail, detail


def test_the_script_reports_the_worktree_after_it_moves_the_refs():
"""Said once, in the run that moved them - and only when something moved.

The `--ref <sha>` branch returns before any ref is created, and a failure stops
with "no refs touched"; neither has a new commit for a worktree to be in step
with, so neither may print this line. Pinned by position: the call sits after
the loop that moves the refs, in the same function that returns 0.
"""
content = SCRIPT.read_text(encoding="utf-8")
# Bound the region at the loop that moves the refs, by its own text. Splitting on
# `update-ref` would not: the first occurrence is inside this PR's own docstring
# (`git update-ref` moves a *ref*), so the region would start above the call and run
# to end of file - a bound that bounds nothing, and every assertion below would hold
# wherever the print block sat (measured by the reviewer of issue #2939).
loop = content.index('for ref in (f"refs/heads/')
verdict = content.index("worktree_state(head)")
assert verdict > loop, (
"the worktree verdict must be printed after the loop that moves the refs"
)
after_refs = content[loop:]
assert "DISCARDS local edits" in after_refs, (
"the remedy must say what it costs"
)
assert "git reset --hard HEAD" in after_refs, "the remedy names the command"
assert content.count("worktree_state(") >= 2, "the helper is defined and used"

# The `--ref <sha>` path returns before any ref is created, so it must not print the
# line at all - the other half of requirement 3.
early_return = content.index("is an object name, not a branch")
assert content.index("worktree_state(head)") > early_return, (
"the verdict must not be printed on the path that creates no ref"
)

Loading