GitHub API (v3): Order tags by creation date

Question

I ran into a problem / question while using the GitHub API.

I need a list of all tags created after a single tag. The only way to do this, is to compare the tags by date. However, the results from the API aren't ordered by date:

Result from the API (rails repository example):

Results from the webinterface:

What i did expect is a list ordered by date. However, as you can see in the pictures: the API is returning v4.0.0rc1 & v4.0.0rc2 before the release of v4.0.0, while 4.0.0 is released after the release candidates. There isn't even a creation / commit date to order at server side.

The releases API isn't a solution either. This API is only returning releases created by Github, not the releases created by tags.

Is there any way to order the tags by date?

Thanks in advance!

Ruben

Answer 1

The Repositories API currently returns tags in the order they would be returned by the "git tag" command, which means they are alphabetically sorted.

The problem with sorting tags chronologically in Git is that there are two types of tags, lightweight and annotated), and for the lightweight type Git doesn't store the creation date.

The Releases/Tags UI currently sorts tags chronologically by the date of the commit to which the tag points to. This again isn't the date on which the tag itself was created, but it does establish a chronological order of things.

Adding this alternative sorting option to the API is on our feature request list.

Answer 2

With GraphQL API v4, we can now filter tags by commit date with field: TAG_COMMIT_DATE inside orderBy. The following will perform ascending sort of tags by commit date :

{
  repository(owner: "rails", name: "rails") {
    refs(refPrefix: "refs/tags/", last: 100, orderBy: {field: TAG_COMMIT_DATE, direction: ASC}) {
      edges {
        node {
          name
          target {
            oid
            ... on Tag {
              message
              commitUrl
              tagger {
                name
                email
                date
              }
            }
          }
        }
      }
    }
  }
}

Test it in the explorer

Here, the tagger field inside target will only be filled for annotated tag & will be empty for lightweight tags.

As date property in tagger gives the creation date of the tag (for annotated tag only), it's possible to filter by creation date on the client side easily (without having to retrieve all the tags 1 by 1)

Note that available options for orderBy.field at this time are TAG_COMMIT_DATE & ALPHABETICAL (no TAG_CREATION_DATE)

Answer 3

Edit: This is now possible using the GitHub GraphQL API.

As workaround, there is a node module for this, which basically fetches the commit details of each tag: github-api-tags-full

> npm install github-api-tags-full github moment

var GitHubApi  = require('github'),
moment     = require('moment'),
githubTags = require('github-api-tags-full');

var github = new GitHubApi({
  version: '3.0.0'
});

githubTags({ user: 'golang', repo: 'go' }, github)
.then(function(tags) {
  var tagsSorted = tags.sort(byAuthorDateAsc).reverse(); // descending
  console.log(tagsSorted); // prints the array of tags sorted by their creation date
});

var byAuthorDateAsc = function(tagA, tagB) {
  return githubCompareDates(
    tagA.commit.author.date,
    tagB.commit.author.date
  );
};
var githubCompareDates = function(dateStrA, dateStrB) {
  return moment(dateStrA).diff(dateStrB);
};

With best regards