michael/github — pull request #30 by JangoSteve (2012-11-27 21:31:22+00:00)
Title: Added functions for retrieving all info for refs, branches, and tags for repo

I started using this recently with jspkg.com. I needed to be able to grab info for both branches and tags for a given github repo. This github.js currently only allows you to fetch a list of branch names. However, there's no reason you couldn't also fetch tag names or any other ref (including github "pulls") using basically the same function.

Also, sometimes you need more than just a list of names. And Github will actually give you the sha, url, and much more in the response. So I abstracted a couple functions, so you can retrieve all this info, but so that `listBranches` still just returns an array of names for backwards compatibility.

To summarize this pull request...

Setup repo object:
```js
var repo = github.getRepo(username, reponame);
```

Existing `listBranches` function:
```js
repo.listBranches(function(err, branches) {});
```
New functions:
```js
// List array of ref objects, returning additional ref info, like sha
// (also, listBranches and all the other following functions, now just delegate to this function internally)
repo.refs(function(err, refs) {});

// Array of branch objects, including additional info
repo.refBranches(function(err, branches) {});

// Array of tag objects, including additional info
repo.refTags(function(err, tags) {});

// List names of all refs (branches, tags, and pulls), similar to existing listBranches function
repo.listRefs(function(err, refs) {});

// List names of all tags
repo.listTags(function(err, tags) {});

// List names of all tags
repo.listTags(function(err, tags) {});

// Array of proper branch objects
repo.branches(function(err, tags) {});

// Array of proper tag objects
repo.tags(function(err, tags) {});
```

I should probably explain the last two functions, which say "proper branch" and "proper tag" objects. What I mean is that, the `refBranches` and `refTags` were made to be consistent with the existing `listBranches` function, which calls Github's "...:repo/git/refs/[:branches|:tags]" URL.

While they technically work, this isn't how they recommend querying their API for branches and tags. They recommend that you [get tags](http://developer.github.com/v3/repos/#list-tags) using the "...:repo/tags" endpoint, and [get branches](http://developer.github.com/v3/repos/#list-branches) using the "...:repo/branches" endpoint.

In testing, I found that the two endpoints actually respond with different sets of data. For example when you use the "refs"-based endpoint, it does return a SHA, but it's the SHA of the actual branch or tag object in git, which isn't incredibly useful. Typically when you retrieve the branch or tag, what you really mean is to fetch the commit to which that branch/tag points to. When you use the direct branch and tag endpoints recommended in Github's API docs, it will actually give you the SHA of the associated commit.

I didn't want to take out any existing functionality or assume I knew the motivation for why github.js has the branches API implemented that way, so I figured I'd just abstract the API call itself such that it's easy to use either one.

Let me know if you have any questions. This is now in production for jspkg.com and working well.