doc: Add fetching single PRs from upstream to productivity.md

willcl-ark commented at 10:12 am on June 20, 2025: member

Current recommendation is to add a new remote fetching all PRs, but this is resource-intensive.

Document a better way to fetch a single PR, and to update a PR which has been force-pushed.

Follows up on a comment from 32774

DrahtBot added the label Docs on Jun 20, 2025

DrahtBot commented at 10:12 am on June 20, 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/32783.

Reviews

See the guideline for information on the review process.

Type	Reviewers
ACK	janb84, pablomartin4btc, theStack, achow101
Concept ACK	BrandonOdiwuor

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

theStack commented at 10:23 am on June 20, 2025: contributor

Concept ACK

in doc/productivity.md:197 in 60bee90451 outdated

192+```bash
193+# Fetch
194+git fetch upstream pull/<number>/head:pr-<number> && git switch pr-<number>
195+
196+# Update (even after force push)
197+git fetch --update-head-ok -f upstream pull<number>/head:pr-<number>

maflcko commented at 10:54 am on June 20, 2025:

0git fetch upstream pull/<number>/head

Could either remove the branch creation, or mention that it optional?

willcl-ark commented at 11:14 am on June 20, 2025:

I split the branch creation version into it’s own command and removed the update command.

in doc/productivity.md:203 in 60bee90451 outdated

198+```
199+
200+...from the command line, substituting `<number>` with the PR number you want to fetch/update.
201+
202+> [!NOTE]
203+> We assume here that the `github.com/bitcoin/bitcoin.git` remote is called "upstream".

maflcko commented at 10:57 am on June 20, 2025:

0> The repository "upstream" must be the one that the pull requests was opened against.

could clarify for the gui repos as well and keep general?

willcl-ark commented at 11:15 am on June 20, 2025:

Made this more generic, but gave examples of this and the GUi repo.

maflcko commented at 10:58 am on June 20, 2025: member

looks like there are typos (see llm linter), also left two more nits

willcl-ark force-pushed on Jun 20, 2025

janb84 commented at 12:02 pm on June 20, 2025: contributor

Concept ACK 83ccae194d0de3e64af54174898f030594be3a4f

in doc/productivity.md:198 in 83ccae194d outdated

193+# Individual fetch
194+git fetch upstream pull/<number>/head
195+
196+# Fetch with automatic branch creation and switch
197+git fetch upstream pull/<number>/head:pr-<number> && git switch pr-<number>
198+```

janb84 commented at 12:05 pm on June 20, 2025:

0git fetch origin pull/<number>/head
1
2# Fetch with automatic branch creation and switch
3git fetch origin pull/<number>/head:pr-<number> && git switch pr-<number>

NIT, lets align the remote names. Line 171 uses origin, lines 181 sets it to upstream-pull here we are using upstream. I think that if you just pull the repo the remote will default to origin?

maflcko commented at 12:08 pm on June 20, 2025:

Line 171 uses origin, lines 181 sets it to upstream-pull here we are using upstream. I think that if you just pull the repo the remote will default to origin?

you can’t use origin, as this is not the one the pull was opened against. upstream-pull is a different remote as well. It really needs to be a dedicated one for each repo

maflcko commented at 12:09 pm on June 20, 2025:

(For reference, fetching by commit hash works across any repo in a GH repo network, so there it doesn’t matter which remote is picked)

janb84 commented at 12:16 pm on June 20, 2025:

Line 171 uses origin, lines 181 sets it to upstream-pull here we are using upstream. I think that if you just pull the repo the remote will default to origin?

you can’t use origin, as this is not the one the pull was opened against. upstream-pull is a different remote as well. It really needs to be a dedicated one for each repo

when i use the command as specified it fails:

0bitcoin]$ git fetch upstream pull/32783/head
1fatal: 'upstream' does not appear to be a git repository
2fatal: Could not read from remote repository.

when I use origin (this is my remote) this works

0bitcoin]$ git remote -v
1origin  https://github.com/bitcoin/bitcoin.git (fetch)
2origin  https://github.com/bitcoin/bitcoin.git (push)

Did I miss a obvious step ?

willcl-ark commented at 12:19 pm on June 20, 2025:

@janb84 most developers here will have two remotes configured:

origin: their personal fork of the repo they make changes in upstream: the upstream repo you make PRs against

These are the most common names for them, but you can set them to be whatever you like.

If you just do git clone https://github.com/bitcoin/bitcoin it will set the remote to origin automagically (unless otherwise directed).

I’d prefer to avoid spelling this out in this document though. I think this is not a “git from scratch” guide, but more advanced tips for better productivity.

maflcko commented at 12:21 pm on June 20, 2025:

when I use origin (this is my remote) this works

I’d expect that normally origin refers to your_user_name/bitcoin-core, not to bitcoin/bitcoin.

This would give:

0$ git fetch origin pull/32783/head
1fatal: couldn't find remote ref pull/32783/head

Maybe, if all of this is more confusing than helpful, it could make sense to just omit it from the docs (and close this pull :sweat_smile: )

Fetching by commit id should work with any remote already, with the only downside of having to do two more clicks to copy the commit id.

janb84 commented at 12:24 pm on June 20, 2025:

I’d prefer to avoid spelling this out in this document though. I think this is not a “git from scratch” guide, but more advanced tips for better productivity.

Ok with that in mind ignore my NIT.

janb84 commented at 12:38 pm on June 20, 2025:

when I use origin (this is my remote) this works

I’d expect that normally origin refers to your_user_name/bitcoin-core, not to bitcoin/bitcoin.

This would give:
0$ git fetch origin pull/32783/head
1fatal: couldn't find remote ref pull/32783/head
Maybe, if all of this is more confusing than helpful, it could make sense to just omit it from the docs (and close this pull 😅 )

Fetching by commit id should work with any remote already, with the only downside of having to do two more clicks to copy the commit id.

No I think it’s quite clear for advanced users, not that hard to figure out. I wasn’t reading this document with advanced users in mind. My mistake.

kevkevinpal commented at 12:43 pm on June 20, 2025:

you can just specify the specific source

ie for this PR git fetch https://github.com/bitcoin/bitcoin pull/32783/head or git fetch https://github.com/bitcoin/bitcoin pull/32783/head:pr-32783 && git switch pr-32783

Dorex45 commented at 10:18 pm on June 20, 2025: none

Hey, thanks for sharing this! I’m still learning, but I found this update to the productivity.md doc really helpful. The idea of fetching PRs directly by number is something I didn’t know it is simple but powerful. One thought: maybe mention that you need to have upstream set as the main Bitcoin repo, just in case someone hasn’t done that yet. Overall, this feels like a useful addition for newcomers like me. Appreciate it!

BrandonOdiwuor commented at 12:14 pm on June 23, 2025: contributor

Concept ACK, great addition if you don’t want to fetch all prs from the remote

pablomartin4btc commented at 4:08 pm on June 24, 2025: member

ACK 83ccae194d0de3e64af54174898f030594be3a4f

In previous section (“Reference PRs easily with refspecs”), also touched recently in #32774, it could be mentioned that the user could use git remove add… instead of adding the remote manually into the git config file.

DrahtBot requested review from theStack on Jun 24, 2025

DrahtBot requested review from janb84 on Jun 24, 2025

DrahtBot requested review from BrandonOdiwuor on Jun 24, 2025

in doc/productivity.md:204 in 83ccae194d outdated

199+
200+...from the command line, substituting `<number>` with the PR number you want to fetch/update.
201+
202+> [!NOTE]
203+> The remote named "upstream" here must be the one that the pull request was opened against.
204+> e.g. github.com/bitcoin/bitcoin.git or for the GUI github.com/bitcoin-core/gui

pablomartin4btc commented at 4:08 pm on June 24, 2025:

nit: looking at the comments around remotes, perhaps you can mention somewhere/ at the end of this note that users could check their setup with git remote -v (and maybe as you said, git clone adds the origin automatically - keeping in mind what you also said that this is not a git guide).

in doc/productivity.md:210 in 83ccae194d outdated

205+
206+Make these easier to use by adding aliases to your git config:
207+
208+```
209+[alias]
210+    # Fetch a and checkout in a new branch a single pr with `git pr 12345`

theStack commented at 6:40 pm on June 25, 2025:

0    # Fetch and checkout a single pr in a new branch with `git pr 12345`

(not a native english speaker, so maybe my word order gut-feeling is tricking me here and it’s also fine as-is… the first “a” seems superflous though)

willcl-ark commented at 7:27 pm on June 25, 2025:

Thanks, fixed in 45b1d39757668939b03b27401c324a938ef0cd8d

DrahtBot requested review from theStack on Jun 25, 2025

doc: Add fetching single PRs from upstream

Current recommendation is to add a new remote fetching all PRs, but this
is resource-intensive.

Document a better way to fetch a single PR, and to update a PR which has
been force-pushed.

45b1d39757

willcl-ark force-pushed on Jun 25, 2025

janb84 commented at 7:30 pm on June 25, 2025: contributor

re ACK 45b1d39757668939b03b27401c324a938ef0cd8d

Changes sinds last ACK:

Small textual changes / fixed typo’s

DrahtBot requested review from pablomartin4btc on Jun 25, 2025

pablomartin4btc commented at 7:56 pm on June 25, 2025: member

re-ACK 45b1d39

theStack approved

theStack commented at 9:42 pm on June 25, 2025: contributor

ACK 45b1d39757668939b03b27401c324a938ef0cd8d

in doc/productivity.md:197 in 45b1d39757

192+```bash
193+# Individual fetch
194+git fetch upstream pull/<number>/head
195+
196+# Fetch with automatic branch creation and switch
197+git fetch upstream pull/<number>/head:pr-<number> && git switch pr-<number>

luke-jr commented at 7:12 pm on June 26, 2025:

Why the experimental git switch instead of git checkout?

luke-jr changes_requested

achow101 commented at 1:25 am on July 1, 2025: member

ACK 45b1d39757668939b03b27401c324a938ef0cd8d

achow101 merged this on Jul 1, 2025

achow101 closed this on Jul 1, 2025

doc: Add fetching single PRs from upstream to productivity.md #32783

Code Coverage & Benchmarks

Reviews