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

pull willcl-ark wants to merge 1 commits into bitcoin:master from willcl-ark:fetch-pr-single changing 1 files +31 −0
  1. 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

  2. DrahtBot added the label Docs on Jun 20, 2025
  3. 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.

  4. theStack commented at 10:23 am on June 20, 2025: contributor
    Concept ACK
  5. 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.
  6. 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.
  7. maflcko commented at 10:58 am on June 20, 2025: member
    looks like there are typos (see llm linter), also left two more nits
  8. willcl-ark force-pushed on Jun 20, 2025
  9. janb84 commented at 12:02 pm on June 20, 2025: contributor
    Concept ACK 83ccae194d0de3e64af54174898f030594be3a4f
  10. 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

  11. 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!
  12. 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
  13. 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.

  14. DrahtBot requested review from theStack on Jun 24, 2025
  15. DrahtBot requested review from janb84 on Jun 24, 2025
  16. DrahtBot requested review from BrandonOdiwuor on Jun 24, 2025
  17. 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).
  18. 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
  19. DrahtBot requested review from theStack on Jun 25, 2025
  20. 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
  21. willcl-ark force-pushed on Jun 25, 2025
  22. janb84 commented at 7:30 pm on June 25, 2025: contributor

    re ACK 45b1d39757668939b03b27401c324a938ef0cd8d

    Changes sinds last ACK:

    • Small textual changes / fixed typo’s
  23. DrahtBot requested review from pablomartin4btc on Jun 25, 2025
  24. pablomartin4btc commented at 7:56 pm on June 25, 2025: member
    re-ACK 45b1d39
  25. theStack approved
  26. theStack commented at 9:42 pm on June 25, 2025: contributor
    ACK 45b1d39757668939b03b27401c324a938ef0cd8d
  27. 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?
  28. luke-jr changes_requested
  29. achow101 commented at 1:25 am on July 1, 2025: member
    ACK 45b1d39757668939b03b27401c324a938ef0cd8d
  30. achow101 merged this on Jul 1, 2025
  31. achow101 closed this on Jul 1, 2025


github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin/bitcoin. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2025-07-08 12:13 UTC

This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me