lint: have git-subtree-check check for backportability #35686

A subtree update is easier to backport when its merge commit is based on the previous subtree merge instead of on a newer master commit. The exact same merge commit can then be reused on release branches, making the backport trivial to verify without rereviewing a newly generated subtree merge.

Update git-subtree-check.sh to locate the merge that introduced the latest subtree squash reachable from COMMIT and error if its first parent is not the previous subtree merge.

Sometimes subtree and Bitcoin Core API changes are incompatible, making it necessary to base an update on a later commit. Add --incompatible to explicitly skip the backportability check in that case.

The CI lint job always sets --incompatible, so we rely on reviewers to run the new check.

As a preparatory refactor, replace getopts with explicit option parsing and add --remote as the preferred long alias for -r.

Example that passes:

test/lint/git-subtree-check.sh src/ipc/libmultiprocess 66b4e30e

Example that errors because the update is not based on the previous subtree merge:

test/lint/git-subtree-check.sh src/ipc/libmultiprocess 02afa661

<!--e57a25ab6845829454e8d69fc972939a-->

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

<!--006a51241073e994b41acfe9ec718e94-->

Code Coverage & Benchmarks

For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/35686.

<!--021abf342d371248e50ceaed478a90ca-->

Reviews

See the guideline and AI policy for information on the review process.

If your review is incorrectly listed, please copy-paste <code>&lt;!--meta-tag:bot-skip--&gt;</code> into the comment that the bot should ignore.

<!--5faf32d7da4f0f540f40219e4f7537a3-->

LLM Linter (✨ experimental)

Possible typos and grammar issues:

• fetch the subtreed remote first -> fetch the subtree remote first [“subtreed” is misspelled]

^{2026-07-28 09:41:23}

I'm not sure. We sometimes cherry-pick commits from the subtree if they contain fixes that need backporting. Is this really solving a problem?

In some rare cases it is required to adjust the code for the subtree bump in the merge commit itself (to avoid build failures on the merge commit itself), so that would warn in that case and somehow encourage build failures?

Also, can you explain how this simplifies "backport"? IIUC you are referring to merging the subtree merge commit as-is into several branches? I think this is nice, and good to keep in mind, but the alternative of having a second similar subtree merge (with only the commit id different) on the backport branch is also fine and harmless?

you are referring to merging the subtree merge commit as-is into several branches? I think this is nice, and good to keep in mind

Yes, we've done this a few times for libmultiprocess: #34804 and #34952 have the exact same merge commit hash, making the pack-port trivial to review.

And it was specifically suggested here: #33439 (comment)

For future releases (31.x and later) we could base new subtree updates on previous subtree updates instead of on newer master commits.

And it was specifically suggested here: #33439 (comment)

For future releases (31.x and later) we could base new subtree updates on previous subtree updates instead of on newer master commits.

I did that in the last update commit (fa911d815dba280f7d4a1b3fe7b786be37afaf75). I guess in theory one could even come up with a copy-pasteable scripted-diff to mark/check such commits. Something like:

$ ./test/lint/commit-script-check.sh HEAD~..HEAD 
Running script for: 84868e9b2c96a14a49cec4a8b30e95bb8857d720

 # Verify last commit is also the last merge subtree commit
 [ "$( git log -1)" == "$( git log -1 src/ipc/libmultiprocess )" ]
 git merge 6d5f753921578eefdd3fce64cfc8ee7951b6cbc4 -m 'dummy'
Merge made by the 'ort' strategy.
 src/ipc/libmultiprocess/doc/versions.md        | 44 ++++++++++++++++++++++++--------------------
 src/ipc/libmultiprocess/include/mp/type-data.h |  3 ++-
 src/ipc/libmultiprocess/include/mp/version.h   |  2 +-
 src/ipc/libmultiprocess/test/mp/test/foo.capnp |  9 ++++++++-
 src/ipc/libmultiprocess/test/mp/test/foo.h     |  4 +++-
 src/ipc/libmultiprocess/test/mp/test/test.cpp  | 23 +++++++++++++++++------
 6 files changed, 55 insertions(+), 30 deletions(-)
OK



$ git log 
commit 84868e9b2c96a14a49cec4a8b30e95bb8857d720 (HEAD)
Merge: a9d1b652f3 6d5f753921

    scripted-diff: ipc: Merge libmul subtree update
    
    -BEGIN VERIFY SCRIPT-
    
     # Verify last commit is also the last merge subtree commit
     [ "$( git log -1)" == "$( git log -1 src/ipc/libmultiprocess )" ]
     git merge 6d5f753921578eefdd3fce64cfc8ee7951b6cbc4 -m 'dummy'
    
    -END VERIFY SCRIPT-

This way, each commit can opt-in or out, and enforce it. But :man_shrugging:

@maflcko I'm mainly concerned about the author forgetting to do this, and the reviewer(s) forgetting to check. That's what this linter fixes. Presumably both the author and reviewer will run this script.

If the author didn't forget, they can just suggest that reviewers confirm that HEAD^1 is the previous subtree merge.

cc @ryanofsky

Code review ACK 4ace058d85b9e7d005b39c31ed5d4eab71afc350. I think having the warning is better than not having it, but a stricter approach would seem better here.

The only reason this check should not be satisfied is when subtree and bitcoin core changes are incompatible. The script could trigger an error instead of warning if that's not the case. Also:

• The warning text seems potentially confusing and hard to act on because it doesn't say what the mismatched hashes mean.
• The documentation seems vague when it says to use the previous subtree "when possible" and because "this makes backporting easier." It should say more specifically when to stack on the subtree and how it does makes backporting easier.
• Skipping this check when the subtree commit is not the HEAD commit seems confusing. Previously the script could find the most recent subtree update by itself and perform a full check. Now it only does a partial check unless it is explicitly given the subtree merge commit hash (or that commit happens to be checked out).

Suggestion: I think a variation of this PR 15b44bfe7e4fa62b867ebcc2465bfaed27d689aa would address all these concerns

Also marco's verify script idea #35686 (comment) seems interesting. It's awkward because the script it is running is non-trivial and includes a hardcoded hash, but could be simplified if the scripted diff called another script in the repository.

@ryanofsky thanks, I took your version, but added an error if $merge somehow isn't set.

I split the options handling refactor into a separate commit. Also added --remote and replaced -r in the documentation (-r is kept as an alias).