[Dextroid17]

What

Adds tools/check_main_sync.py, an offline check a contributor runs before pushing or reporting a test result. It reports whether a branch is in step with main:

• how many commits the branch is ahead of and behind main
• whether git merge-tree merges it cleanly, and the conflicting files when it does not
• the files changed on both sides since the merge base, and the merged pull requests that touched them

--fetch updates the base first, --strict also fails when the branch is behind, and the exit code is 1 on a conflict. It complements tools/pr_overlap.py, which compares open PRs with each other through the GitHub API; this compares one branch with main and needs only git.

Tested

Linux, git 2.56, Python 3. tools/tests/test_check_main_sync.py (7 tests, registered as check_main_sync) builds throwaway repositories for a level branch, a behind branch, a conflict, a clean merge with shared files, paths with spaces and non-ASCII characters, unrelated histories and a missing base. Breaking the conflict detection, the NUL splitting, --first-parent or the ahead/behind direction each fails the tests. Run against #4730's head it reports the CMakeLists.txt conflict and the merged PRs behind it. check_conventions.py passes. Not tested on Windows or macOS.

Checklist

• Based on current main; no other open PR implements the same functions
• One topic per PR; follow-ups go in a new PR
• No comments in code except technical debt
• Unimplemented paths throw; no silent stubs
• No notes, investigation .md files or images added to the repository
• New third-party code is a submodule built from source
• Generic behaviour, not specific to one title
• Depends on: none
• Unblocks: none
• AI-assisted: yes

[johnmaia]

Windows run, since the description says Windows is untested. Setup: Windows 11 (26300), WinLibs GCC 15.2.0 r7, Python 3.12, Git for Windows, Release, BUILD_TESTING=ON, ctest -j4 --timeout 300. Head 851b66b merged into main 69b4ca5.

• check_main_sync passes, and the full suite passes 1082 of 1082.

• On real branches in a Windows clone, with --base origin/main:

  • feat(agc): remap a viewport depth range the device cannot express into the vertex shader #4650's head: "1 ahead and 139 behind", merge: CONFLICT in 2 file(s) (RequestSerializer.cpp, docs/dev/debt/libSceAgcDriver.md), 14 files changed on both sides, exit 1.
  • fix(libSceNet): accept MSG_DONTWAIT in the send and receive calls #4673's head: "1 ahead and 664 behind", merge: clean, 3 files on both sides with the merged PRs that touched them (feat(libkernel): implement kqueue, kevent and file events #3764, fix(libkernel): give guest sockets ordinary descriptor numbers below FD_SETSIZE #4391, feat(libSceNetCtl): add sceNetCtlGetIfStat #4682), exit 0, and exit 1 with --strict.

  Both match GitHub's mergeability for those PRs.

AI-assisted: yes (Claude Code)

[adriadam10]

Checked on the PR merged onto current main: check_main_sync passes, and fails when tools/check_main_sync.py is reverted. On this PR's own head against upstream/main the tool reports the merge as clean, CMakeLists.txt as changed on both sides, and the merged PRs that touched it. The Windows run by @johnmaia covers the platform the description left untested. Merging once the full Build is green.