doc: how to update a subtree #33568

Sjors commented at 3:18 PM on October 7, 2025: member

We have instructions on how to verify a subtree update, but not on how to perform one.

DrahtBot added the label Docs on Oct 7, 2025

DrahtBot commented at 3:18 PM on October 7, 2025: contributor

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

Code Coverage & Benchmarks

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

Reviews

See the guideline for information on the review process.

Type	Reviewers
ACK	yuvicc, janb84, furszy, achow101

If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.

Sjors force-pushed on Oct 7, 2025

in doc/developer-notes.md:1125 in da373a20a1 outdated

1118 | @@ -1119,6 +1119,12 @@ to check a subtree directory for consistency with its upstream repository.
1119 |  
1120 |  The tool instructions also include a list of the subtrees managed by Bitcoin Core.
1121 |  
1122 | +To update a subtree, follow the instructions for adding it as a remote and then:
1123 | +
1124 | +```sh
1125 | +git subtree pull --prefix=src/ipc/libmultiprocess libmultiprocess master --squash

furszy commented at 3:58 PM on October 7, 2025:

Need to add the remote first. E.g.

git remote add libmultiprocess <repo_URL>
git subtree pull --prefix=src/ipc/libmultiprocess libmultiprocess master --squash

Sjors commented at 4:14 PM on October 7, 2025:

That's explained in the linter doc that's linked right above, but I can duplicate it if needed.

fjahr commented at 5:44 PM on October 7, 2025:

Might be good to duplicate for the avoidance of doubt.

Sjors commented at 6:14 PM on October 7, 2025:

Done

achow101 commented at 10:17 PM on October 8, 2025:

It's actually not necessary to add it as a remote. You can give the repo url directly and it will fetch as needed. This avoids adding a bunch of unnecessary refs to your repo.

Sjors commented at 7:45 AM on October 9, 2025:

We also recommend this for the verification process and I find it much more convenient than looking up the full URL. I haven't run out of refs :-)

fjahr commented at 5:45 PM on October 7, 2025: contributor

Looks good to me, this matches what I run to get experimental secp branches. I think @furszy 's comment should be addressed then this should be good to go.

Sjors force-pushed on Oct 7, 2025

in doc/developer-notes.md:1125 in 3a2f50a75b

1118 | @@ -1119,6 +1119,19 @@ to check a subtree directory for consistency with its upstream repository.
1119 |  
1120 |  The tool instructions also include a list of the subtrees managed by Bitcoin Core.
1121 |  
1122 | +To fully verify or update a subtree, add it as a remote:
1123 | +
1124 | +```sh
1125 | +git remote add --fetch libmultiprocess https://github.com/bitcoin-core/libmultiprocess.git

furszy commented at 7:25 PM on October 7, 2025:

No need to add the --fetch option. You added a git fetch below.

Sjors commented at 6:38 AM on October 8, 2025:

You only need to add it as a remote once, but each subsequent update requires a fetch. I'll drop --fetch from the first command though.

furszy commented at 1:36 PM on October 8, 2025:

yeah, that's what I meant.

furszy commented at 7:26 PM on October 7, 2025: member

Concept ACK

doc: how to update a subtree a1226bc760

Sjors force-pushed on Oct 8, 2025

yuvicc commented at 7:45 AM on October 8, 2025: contributor

ACK a1226bc760c70a22ef4a197d5690aca4d83cb74c

This will be useful for new devs while verifying the subtree.

DrahtBot requested review from furszy on Oct 8, 2025

in doc/developer-notes.md:1122 in a1226bc760

1118 | @@ -1119,6 +1119,19 @@ to check a subtree directory for consistency with its upstream repository.
1119 |  
1120 |  The tool instructions also include a list of the subtrees managed by Bitcoin Core.
1121 |  
1122 | +To fully verify or update a subtree, add it as a remote:

janb84 commented at 9:28 AM on October 8, 2025:

### Updating subtrees

To fully verify or update a subtree, add it as a remote:

NIT add a sub heading to better indicate it's a subsection. This will help the reader in finding the section and it will nicely bind the section together.

Sjors commented at 9:59 AM on October 8, 2025:

But then I have to move the text below this too, or add even more paragraphs. So going to leave it as is for now.

janb84 commented at 9:36 AM on October 8, 2025: contributor

ACK a1226bc760c70a22ef4a197d5690aca4d83cb74c

This pr adds a section to subtrees. This section describes how to verify or update a subtree ( commands etc). Adding of this section will help new contributors do a subtrees update without spending time to search how to do this.

Added small NIT to add a subsection header, to better subdivide the section. Feel free to ignore.

furszy commented at 1:36 PM on October 8, 2025: member

ACK a1226bc760c70a22ef4a197d5690aca4d83cb74c

fjahr commented at 3:15 PM on October 9, 2025: contributor

ACk a1226bc760c70a22ef4a197d5690aca4d83cb74c

achow101 commented at 5:59 PM on October 9, 2025: member

ACK a1226bc760c70a22ef4a197d5690aca4d83cb74c

achow101 merged this on Oct 9, 2025

achow101 closed this on Oct 9, 2025

sedited referenced this in commit f50d90fcbb on Oct 29, 2025

stickies-v referenced this in commit a785fe6759 on Nov 5, 2025

stringintech referenced this in commit b82132c4d1 on Nov 6, 2025

yuvicc referenced this in commit f620a2206b on Nov 16, 2025

Kino1994 referenced this in commit a085993f0a on Jun 28, 2026

BigcoinBGC referenced this in commit d878ec88b7 on Jun 30, 2026

Kino1994 referenced this in commit df0ab345bb on Aug 19, 2026

bitcoin locked this on Oct 9, 2026