2

In various places, looking for instructions on how to create a local branch from a GitHub Pull Request, I have seen two versions:

git fetch upstream refs/pull/PR_ID/head:NEW_LOCAL_BRANCH

and

git fetch upstream pull/PR_ID/head:NEW_LOCAL_BRANCH

My question is, what's the difference between including "refs" in the address, and not including it?
Both seem to work fine.

Daniel Goldfarb
  • 6,937
  • 5
  • 29
  • 61

2 Answers2

5

The prefix refs/pull/ is a ref (or reference) namespace invented—if that word isn't too strong—by GitHub to use for their Pull Request feature. It's not a standard Git namespace, and Git by default will ignore names in the refs/pull/ namespace when fetching.

As matt noted, if you use an abbreviated ref (anywhere, not just in a refspec), Git will attempt to match it up with a full ref if possible. The precise rules for doing this matching depend on where you use such a name. The usual set is outlined in the gitrevisions documentation, but it's talking about local refs that exist only in your own repository; when you're doing git fetch or git push, some refs are not local and these rules get bent up a little.

torek
  • 448,244
  • 59
  • 642
  • 775
  • Is this "illegal"? Does git specify that anything not under `refs/heads` `refs/tags` is fair game as an extension point? – markson edwardson Dec 16 '22 at 01:06
  • 1
    There's no "legal" vs "illegal" as far as Git goes: things not specified in the documentation are fair game for changes both inside and outside Git, more or less. You can write your own Git commands, and when you do that, you can make your own educated guesses about what some future Git release might use. But you might guess wrong! GitHub, Bitbucket, and GitLab have a certain amount of leverage over the Git authors though, because they're so widely used. If *I* pick `refs/zoo/` to hold my Animals Extension, and the Git authors later pick `refs/zoo/` for something different, well... – torek Dec 16 '22 at 05:05
4

what's the difference between including "refs" in the address, and not including it?

Including it gives a reference that works, directly.

Not including it means that Git has to figure out what you mean. It does that by trying stuff. One of the first things it tries is to put refs/ in front of what you said — and by golly, that works.

(For a recital of the full procedure that Git uses to figure out what you mean, see

https://git-scm.com/docs/gitrevisions

Look at the third entry under Specifying Revisions.)

matt
  • 515,959
  • 87
  • 875
  • 1,141