Git References

A Git reference (git ref) is just a file that contains a Git commit SHA-1 hash. When referring to a Git commit, you can use the Git reference, which is an easy-to-remember name, rather than the hash. The Git reference can be rewritten to point to a new commit. A branch is just a Git reference that stores the new Git commit hash. These endpoints allow you to read and write references to your Git database on GitHub. See the Git Database API for more details.

Get a reference
Get all references
Create a reference
Update a reference
Delete a reference

Get a reference

Returns a single reference from your Git database.

The ref in the URL must be formatted as heads/<branch name> for branches and tags/<tag name> for tags. If the ref doesn't exist in the repository, but existing refs start with ref they will be returned as an array. If the ref doesn't match an existing ref or any prefixes, a 404 is returned.

Note: You need to explicitly request a pull request to trigger a merge commit creation. For more information, see "Checking mergeability of pull requests".

GET /repos/:owner/:repo/git/refs/:ref

Example getting a branch

To get the reference for a branch named skunkworkz/featureA, the endpoint route would be:

GET /repos/octocat/Hello-World/git/refs/heads/skunkworkz/featureA

Response

Status: 200 OK

{
  "ref": "refs/heads/featureA",
  "node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlQQ==",
  "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/featureA",
  "object": {
    "type": "commit",
    "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd",
    "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/aa218f56b14c9653891f9e74264a383fa43fefbd"
  }
}

Example matching a partial branch name

A call to get the data for a branch named feature, which doesn't exist, would return head refs including featureA and featureB.

GET /repos/octocat/Hello-World/git/refs/heads/feature

Response

Status: 200 OK

[
  {
    "ref": "refs/heads/feature-a",
    "node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlLWE=",
    "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/feature-a",
    "object": {
      "type": "commit",
      "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd",
      "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/aa218f56b14c9653891f9e74264a383fa43fefbd"
    }
  },
  {
    "ref": "refs/heads/feature-b",
    "node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlLWI=",
    "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/feature-b",
    "object": {
      "type": "commit",
      "sha": "612077ae6dffb4d2fbd8ce0cccaa58893b07b5ac",
      "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/612077ae6dffb4d2fbd8ce0cccaa58893b07b5ac"
    }
  }
]

Get all references

Returns an array of all the references from your Git database, including notes and stashes if they exist on the server. Anything in the namespace is returned, not just heads and tags. If there are no references to list, a 404 is returned.

Note: You need to explicitly request a pull request to trigger a merge commit creation. For more information, see "Checking mergeability of pull requests".

GET /repos/:owner/:repo/git/refs

Example getting all references for a repository

GET /repos/octocat/Hello-World/git/refs

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"

[
  {
    "ref": "refs/heads/master",
    "node_id": "MDM6UmVmcmVmcy9oZWFkcy9tYXN0ZXI=",
    "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/master",
    "object": {
      "type": "commit",
      "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd",
      "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/aa218f56b14c9653891f9e74264a383fa43fefbd"
    }
  },
  {
    "ref": "refs/heads/gh-pages",
    "node_id": "MDM6UmVmcmVmcy9oZWFkcy9naC1wYWdlcw==",
    "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/gh-pages",
    "object": {
      "type": "commit",
      "sha": "612077ae6dffb4d2fbd8ce0cccaa58893b07b5ac",
      "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/612077ae6dffb4d2fbd8ce0cccaa58893b07b5ac"
    }
  },
  {
    "ref": "refs/tags/v0.0.1",
    "node_id": "MDM6UmVmcmVmcy90YWdzL3YwLjAuMQ==",
    "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/tags/v0.0.1",
    "object": {
      "type": "tag",
      "sha": "940bd336248efae0f9ee5bc7b2d5c985887b16ac",
      "url": "https://api.github.com/repos/octocat/Hello-World/git/tags/940bd336248efae0f9ee5bc7b2d5c985887b16ac"
    }
  }
]

Example getting references for a sub-namespace

You can also request a sub-namespace. For example, to get all the tag references, you can call:

GET /repos/octocat/Hello-World/git/refs/tags

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"

[
  {
    "ref": "refs/tags/v0.0.1",
    "node_id": "MDM6UmVmcmVmcy90YWdzL3YwLjAuMQ==",
    "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/tags/v0.0.1",
    "object": {
      "type": "tag",
      "sha": "940bd336248efae0f9ee5bc7b2d5c985887b16ac",
      "url": "https://api.github.com/repos/octocat/Hello-World/git/tags/940bd336248efae0f9ee5bc7b2d5c985887b16ac"
    }
  }
]

Create a reference

Creates a reference for your repository. You are unable to create new references for empty repositories, even if the commit SHA-1 hash used exists. Empty repositories are repositories without branches.

POST /repos/:owner/:repo/git/refs

Parameters

Name	Type	Description
`ref`	`string`	Required. The name of the fully qualified reference (ie: `refs/heads/master`). If it doesn't start with 'refs' and have at least two slashes, it will be rejected.
`sha`	`string`	Required. The SHA1 value for this reference.

Input

{
  "ref": "refs/heads/featureA",
  "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd"
}

Response

Status: 201 Created
Location: https://api.github.com/repos/octocat/Hello-World/git/refs/heads/featureA

{
  "ref": "refs/heads/featureA",
  "node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlQQ==",
  "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/featureA",
  "object": {
    "type": "commit",
    "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd",
    "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/aa218f56b14c9653891f9e74264a383fa43fefbd"
  }
}

Update a reference

PATCH /repos/:owner/:repo/git/refs/:ref

Parameters

Name	Type	Description
`sha`	`string`	Required. The SHA1 value to set this reference to
`force`	`boolean`	Indicates whether to force the update or to make sure the update is a fast-forward update. Leaving this out or setting it to `false` will make sure you're not overwriting work. Default: `false`

Input

{
  "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd",
  "force": true
}

Response

Status: 200 OK

{
  "ref": "refs/heads/featureA",
  "node_id": "MDM6UmVmcmVmcy9oZWFkcy9mZWF0dXJlQQ==",
  "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/featureA",
  "object": {
    "type": "commit",
    "sha": "aa218f56b14c9653891f9e74264a383fa43fefbd",
    "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/aa218f56b14c9653891f9e74264a383fa43fefbd"
  }
}

Delete a reference

DELETE /repos/:owner/:repo/git/refs/:ref

Example deleting a branch

DELETE /repos/octocat/Hello-World/git/refs/heads/feature-a

Response

Status: 204 No Content

Example deleting a tag

DELETE /repos/octocat/Hello-World/git/refs/tags/v1.0

Response

Status: 204 No Content