Git branch statistics

Last Update: 5/23/2017

api-version = 1.0

If you haven't already, look at the information on getting started with these APIs.

Branch statistics indicate how far behind and ahead a branch is from the default branch. Branch A is "ahead" of branch B if branch A contains commits not in branch B's history. In the picture below, feature1 is 2 commits ahead of and 3 commits behind master.

Two branches illustrating ahead/behind

There are code samples available for this endpoint.

Get branch statistics

GET https://{instance}/DefaultCollection/{project}/_apis/git/repositories/{repository}/stats/branches[/{name}]?api-version={version}
Parameter Type Default Notes
URL
instance string VS Team Services account ({account}.visualstudio.com) or TFS server ({server:port}).
project string ID or name of the team project. Optional if specifying an ID for repository.
repository string ID of the repository.
name string Name of the branch.
Query
api-version string Version of the API to use.
baseVersionType enum { Branch, Tag, Commit } Branch Item versions.
baseVersion string master Item versions.
NOTE

Repositories have both a name and an identifier. Identifiers are globally unique, but several projects may contain a repository of the same name. You don't need to include the project if you specify a repository by ID. However, if you specify a repository by name, you must also specify the project (by name or ID).

For all branches

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/git/repositories/278d5cd2-584d-4b63-824a-2ba458937249/stats/branches?api-version=1.0

Sample response

Status code: 200
{
  "count": 3,
  "value": [
    {
      "commit": {
        "commitId": "67cae2b029dff7eb3dc062b49403aaedca5bad8d",
        "author": {
          "name": "Chuck Reinhart",
          "email": "fabrikamfiber3@hotmail.com",
          "date": "2014-01-29T23:52:56Z"
        },
        "committer": {
          "name": "Chuck Reinhart",
          "email": "fabrikamfiber3@hotmail.com",
          "date": "2014-01-29T23:52:56Z"
        },
        "comment": "home page",
        "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/git/repositories/278d5cd2-584d-4b63-824a-2ba458937249/commits/67cae2b029dff7eb3dc062b49403aaedca5bad8d"
      },
      "name": "develop",
      "aheadCount": 1,
      "behindCount": 17,
      "isBaseVersion": false
    },
    {
      "commit": {
        "parents": [
          "fe17a84cc2dfe0ea3a2202ab4dbac0706058e41f"
        ],
        "treeId": "8263e7232a2331c563d737e4fc4e9c66a8286c63",
        "commitId": "23d0bc5b128a10056dc68afece360d8a0fabb014",
        "author": {
          "name": "Norman Paulk",
          "email": "Fabrikamfiber16@hotmail.com",
          "date": "2014-06-30T18:10:55Z"
        },
        "committer": {
          "name": "Norman Paulk",
          "email": "Fabrikamfiber16@hotmail.com",
          "date": "2014-06-30T18:10:55Z"
        },
        "comment": "Better description for hello world\n",
        "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/git/repositories/278d5cd2-584d-4b63-824a-2ba458937249/commits/23d0bc5b128a10056dc68afece360d8a0fabb014"
      },
      "name": "master",
      "aheadCount": 0,
      "behindCount": 0,
      "isBaseVersion": true
    },
    {
      "commit": {
        "parents": [
          "fe17a84cc2dfe0ea3a2202ab4dbac0706058e41f"
        ],
        "treeId": "8263e7232a2331c563d737e4fc4e9c66a8286c63",
        "commitId": "23d0bc5b128a10056dc68afece360d8a0fabb014",
        "author": {
          "name": "Norman Paulk",
          "email": "Fabrikamfiber16@hotmail.com",
          "date": "2014-06-30T18:10:55Z"
        },
        "committer": {
          "name": "Norman Paulk",
          "email": "Fabrikamfiber16@hotmail.com",
          "date": "2014-06-30T18:10:55Z"
        },
        "comment": "Better description for hello world\n",
        "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/git/repositories/278d5cd2-584d-4b63-824a-2ba458937249/commits/23d0bc5b128a10056dc68afece360d8a0fabb014"
      },
      "name": "npaulk/feature",
      "aheadCount": 0,
      "behindCount": 0,
      "isBaseVersion": true
    }
  ]
}

For a single branch

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/git/repositories/278d5cd2-584d-4b63-824a-2ba458937249/stats/branches/develop?api-version=1.0

Sample response

Status code: 200
{
  "commit": {
    "commitId": "67cae2b029dff7eb3dc062b49403aaedca5bad8d",
    "author": {
      "name": "Chuck Reinhart",
      "email": "fabrikamfiber3@hotmail.com",
      "date": "2014-01-29T23:52:56Z"
    },
    "committer": {
      "name": "Chuck Reinhart",
      "email": "fabrikamfiber3@hotmail.com",
      "date": "2014-01-29T23:52:56Z"
    },
    "comment": "home page",
    "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/git/repositories/278d5cd2-584d-4b63-824a-2ba458937249/commits/67cae2b029dff7eb3dc062b49403aaedca5bad8d"
  },
  "name": "develop",
  "aheadCount": 1,
  "behindCount": 17,
  "isBaseVersion": false
}

For a tag or commit

You can leave out the branch name and instead specify baseVersion and baseVersionType to get stats for a commit.

Sample request

GET https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/git/repositories/278d5cd2-584d-4b63-824a-2ba458937249/stats/branches/develop?baseVersionType=commit&baseVersion=67cae2b029dff7eb3dc062b49403aaedca5bad8d&api-version=1.0

Sample response

Status code: 200
{
  "commit": {
    "parents": [
      "be67f8871a4d2c75f13a51c1d3c30ac0d74d4ef4"
    ],
    "treeId": "f9a2a90cbeac747fff9dadcf77ff5bcd12b65a44",
    "commitId": "67cae2b029dff7eb3dc062b49403aaedca5bad8d",
    "author": {
      "name": "Chuck Reinhart",
      "email": "fabrikamfiber3@hotmail.com",
      "date": "2014-01-29T23:52:56Z"
    },
    "committer": {
      "name": "Chuck Reinhart",
      "email": "fabrikamfiber3@hotmail.com",
      "date": "2014-01-29T23:52:56Z"
    },
    "comment": "home page\n",
    "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/git/repositories/278d5cd2-584d-4b63-824a-2ba458937249/commits/67cae2b029dff7eb3dc062b49403aaedca5bad8d"
  },
  "name": "develop",
  "aheadCount": 0,
  "behindCount": 0,
  "isBaseVersion": true
}