Support new Git reference get/list endpoints

[bluekeyes]

Sometime in 2019¹, GitHub quietly hid the old /repos/:owner/:repo/git/refs[/...] endpoint in favor of two new endpoints that have the same functionality but provide consistent responses:

• GET /repos/:owner/:repo/git/ref/:ref - https://developer.github.com/v3/git/refs/#get-a-single-reference; always returns a ref or an error
• GET /repos/:owner/:repo/git/matching-refs/:ref - https://developer.github.com/v3/git/refs/#list-matching-references; always returns a (possibly empty) list

I'd like to use these endpoints in the library because the current methods make it awkward to test if a reference exists, but I was unsure what should happen to the existing methods.

1. Modify the existing functions to use the new endpoints.

   • GetRef will behave the same but will return different concrete errors in the error cases (i.e. a standard ErrorResponse with a 404 code if the ref does not exist.)
   • GetRefs will mostly behave the same, but will return an empty list instead of an error if no refs match and will duplicate the functionality of ListRefs if an empty refs is used as an argument. The "error on empty" behavior could be retained if desired.
   • ListRefs will behave the same, but is technically redundant.

2. Modify GetRef, leave GetRefs and ListRefs alone, and add a new ListMatchingRefs method. I think this will ultimately be confusing, there are 3 methods that do nearly the same thing, two of which are undocumented in the GitHub API.

3. Modify GetRef, remove GetRefs and ListRefs, and add a new ListMatchingRefs method. This matches the API best, but is not backwards compatible and probably won't work for people still using GitHub Enterprise 2.18 and earlier.

What sounds best? I started implementing (1) but realized it might be better to cleanly break the API and add a new method, if breaking backwards compatibility is acceptable. I'm happy to implement whichever you are willing to support.

---

¹The GitHub Enterprise 2.18 docs have the old endpoints, while the 2.19 docs have the new endpoints, putting the change between August and November, although github.com probably got it earlier.

[gmlewis]

Thank you for the research and the detailed analysis, @bluekeyes! It is greatly appreciated.

Yes, we prefer to match the official GitHub v3 API as closely as possible so that there is the least amount of confusion, even if this means bumping the major version of the repo due to the breaking API change (as can be seen, we are at v31 right now and already have another breaking change ready for v32 😄).

So I agree that Option # 3 sounds best, and welcome PRs. Please check out CONTRIBUTING.md which reminds you to run go generate ./... before pushing your PR.

Thanks again!

[bluekeyes]

Thanks for the advice, @gmlewis! I implemented option 3 in #1513.